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

Get your agent buying from any merchant URL in 15 minutes.

Let your agent buy from any merchant with a single API. Hand the **Agent Checkouts API** a product URL and a spending cap, and Crossmint completes the checkout on your user's behalf — paying with any method the merchant accepts.

By the end you will have a script that saves a buyer profile, creates a checkout from a product URL, polls it through its lifecycle, embeds the live browser session for the user to watch, answers each pending action, and reads the final receipt.

<CardGroup>
  <Card title="Try the live demo" icon="rocket" href="https://agent-checkouts.demos-crossmint.com">
    See the full flow in action without setting anything up locally.
  </Card>

  <Card title="Agent Checkouts Quickstart" icon="code" href="https://github.com/Crossmint/agent-checkout-quickstart">
    Explore the full reference implementation this guide is based on.
  </Card>
</CardGroup>

<Warning>Agent Checkouts can only be tested in **production** today — there is no staging environment for it. Use a `ck_production_...` key and **live** auth credentials; test/staging credentials fail with `401`.</Warning>

## How it works

A checkout walks a simple lifecycle with **no webhooks in v1** — you poll until it reaches a terminal state:

1. **Create** a checkout and get back an `id`.
2. **Poll** `GET /{id}` (≈ every 1.5s) as it walks the lifecycle.
3. **Embed** the live browser session in an `<iframe>` so the user can watch.
4. **Respond** to each `pendingUserAction` by rendering a form from the JSON Schema it carries.
5. Read the terminal result — a **receipt** on success, or a **failure reason**.

## Prerequisites

* Node.js 20+
* A **client-side API key** (`ck_production_...`) with the scopes `agent-checkouts.create | read | update | cancel`, plus `agent-checkouts.buyer-profiles.create | read | update | delete` for buyer profiles
* An **external auth provider** (e.g. Stytch, Auth0, Clerk) that issues JWTs for your signed-in users — the key alone is not enough

## Setup

<Steps>
  <Step title="Get a Crossmint API key">
    Sign in to the <a href="https://www.crossmint.com/console">Crossmint Console</a> and create a project.

    Under **API Keys**, create a **client-side** key (`ck_production_...`) with the `agent-checkouts.create | read | update | cancel` and `agent-checkouts.buyer-profiles.create | read | update | delete` scopes, and add your app's origin under the **allowed-origins** setting. The `ck_` key is public by design — it authenticates against the browser's `Origin`, so restrict it with allowed-origins rather than treating it as a secret.
  </Step>

  <Step title="Register your auth provider in Crossmint">
    Checkouts run *on behalf of a signed-in user*, so every request carries **two** credentials — your `ck_` key and the user's JWT.

    In the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a>, under **3P Auth providers**, register the provider whose JWTs you want Crossmint to trust. Crossmint will then accept `Authorization: Bearer <jwt>` headers minted by that provider.

    <Warning>Without the `Authorization: Bearer <jwt>` header the API returns `401`, even with a valid key. The JWT must come from your **live** provider environment — a test token is rejected. Read the token fresh on each call so refreshed sessions are picked up.</Warning>
  </Step>

  <Step title="Configure your client">
    Point your client at the production API and send both credentials on every request.

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

    const headers = {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_API_KEY, // ck_production_... client-side key
        Authorization: `Bearer ${jwt}`, // the signed-in user's JWT
    };
    ```
  </Step>

  <Step title="Save a buyer profile">
    A **buyer profile** is a reusable set of the buyer's **name, contact, and shipping** (there is deliberately no payment block). Save one, then attach it to any checkout so the agent fills those fields from it instead of asking every time.

    ```typescript theme={null}
    const res = 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", // ISO 3166-2, country-prefixed
                postalCode: "94105",
                countryCode: "US", // ISO 3166-1 alpha-2, required
            },
        }),
    });

    const { id: buyerProfileId } = await res.json(); // 201 — save this
    ```
  </Step>

  <Step title="Create a checkout">
    Give the agent a `target.url`, an optional `request` (natural-language instruction), and a **required** `maxCost`. Attach the saved profile with `buyerProfileId`, and save the returned `id`.

    ```typescript theme={null}
    const res = await fetch(BASE_URL, {
        method: "POST",
        headers,
        body: JSON.stringify({
            target: {
                kind: "direct_url",
                url: "https://merchant.example/products/classic-tee",
                request: "buy the medium in black", // optional
            },
            buyerProfileId, // attach the saved buyer profile
            constraints: {
                maxCost: { amount: "100.00", currency: "USD" }, // required
            },
        }),
    });

    const { id } = await res.json();
    ```

    The checkout fails with `max_cost_exceeded` rather than ever spending above `maxCost`.

    The `request` is where you steer the agent. The more you specify up front — size, delivery option, billing address, which payment method to use — the fewer questions it stops to ask; say nothing and it surfaces a pending action for each. The one thing you can't put here is **card details** — the agent always collects those through a payment user action (the step below).
  </Step>

  <Step title="Poll the lifecycle">
    There are **no webhooks in v1** — poll `GET /{id}` (≈ every 1.5s) until the status is terminal. Swallow transient poll errors and retry rather than killing the loop.

    ```typescript theme={null}
    const TERMINAL = ["succeeded", "failed", "cancelled"];

    async function getCheckout(id: string) {
        const res = await fetch(`${BASE_URL}/${id}`, { headers, cache: "no-store" });
        return res.json();
    }

    let checkout = await getCheckout(id);
    while (!TERMINAL.includes(checkout.status)) {
        // Show the user the live session (next step)…
        if (checkout.status === "awaiting_user_action") {
            await respond(checkout); // …and answer when asked (step after)
        }
        await new Promise((r) => setTimeout(r, 1500));
        checkout = await getCheckout(id);
    }
    ```
  </Step>

  <Step title="Embed the live browser session">
    The view returns a `browser.embedUrl` so your user can watch (and, with `write` permission, interact with) the session the agent is driving.

    ```tsx theme={null}
    // embedUrl may be relative to the Crossmint origin — resolve it against the
    // API host, or an <iframe src> resolves it against your origin and 404s.
    const embedUrl = new URL(checkout.browser.embedUrl, "https://www.crossmint.com").toString();

    <iframe src={embedUrl} allow="clipboard-write" />;
    ```
  </Step>

  <Step title="Respond to user actions">
    When `status` is `awaiting_user_action`, the view carries a `pendingUserAction` with a `responseSchema` (a JSON Schema). **Render the form dynamically from that schema** — never hardcode fields — so the same code handles shipping, payment, or size selection.

    ```typescript theme={null}
    async function respond(checkout) {
        const action = checkout.pendingUserAction;
        // action.responseSchema → walk .properties to render inputs
        // action.expiresAt      → respond before this or the checkout fails

        await fetch(`${BASE_URL}/${checkout.id}/actions/${action.id}`, {
            method: "POST",
            headers,
            body: JSON.stringify({
                action: "submit",
                values: { fullName: "Ada Lovelace", country: "GB" /* … */ },
            }),
        });
    }
    ```

    <Warning>The `actionId` goes in the **path only** — including it in the body is rejected. More actions may follow (e.g. payment after shipping), so **return to polling** after each response.</Warning>

    **Payment is one of these actions.** When the agent reaches the payment step it raises a payment action, and you submit the card details in the `values` you send back — you can't pre-supply them in the create request. Submit **only an agent card or a single-use / virtual card number, never a real, reusable card number (PAN)**: a scoped or one-time number can't be reused if it leaks; a reusable PAN can.

    <Accordion title="Why single-use and virtual card numbers are safe to submit, but a real PAN is not">
      The card networks put scoped, one-time numbers outside PCI-DSS scope precisely because a leak can't be reused:

      * **Visa:** single-use virtual Visa account numbers are *"out of scope for PCI DSS protection requirements based on the low risk of fraud,"* and EMVCo payment tokens *"are not considered to be Visa account data and are not in scope for PCI DSS"* — while *"all other Visa primary account numbers (PANs) must be protected in accordance with PCI DSS"* ([Expanded Position on PCI DSS Applicability for Virtual Visa Accounts](https://usa.visa.com/dam/VCOM/global/support-legal/documents/expanded-pci-dss.pdf)).
      * **Mastercard:** Single-Use Virtual Card Numbers are treated as out of PCI-DSS scope because the number is disabled after one authorization and cannot be reused ([Virtual Card Numbers and SDP Compliance FAQs](https://www.mastercard.com/content/dam/public/mastercardcom/globalrisk/pdf/Virtual%20Card%20Numbers%20and%20SDP%20Compliance%20FAQs%20\(15%20February%202022\).pdf)).

      The agent-card programs that issue these scoped tokens: [Visa Intelligent Commerce](https://developer.visa.com/capabilities/visa-intelligent-commerce) and [Mastercard Agent Pay](https://www.mastercard.com/us/en/business/artificial-intelligence/mastercard-agent-pay.html).
    </Accordion>
  </Step>

  <Step title="Read the result">
    When the checkout reaches a terminal state, read the outcome.

    ```typescript theme={null}
    if (checkout.status === "succeeded") {
        const { total, merchantOrderId, evidence } = checkout.receipt;
    }

    if (checkout.status === "failed") {
        const { reason, message } = checkout.failure;
        // reason: max_cost_exceeded | user_cancelled | user_action_expired | automation_failed
    }
    ```

    To stop a checkout early, call `DELETE /{id}` — it's accepted immediately and the status flips to `cancelled` on a later poll.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Provide Purchase Context" icon="address-card" href="/agents/payment-flows/agent-checkouts-buyer-context">
    Buyer profiles and the buyer request — prefill identity, shipping, and intent.
  </Card>

  <Card title="Choose a Payment Method" icon="credit-card" href="/agents/payment-flows/agent-checkouts-payment-method">
    Supported methods, and how to pass a card safely.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/agent-checkouts/create-agent-checkout">
    The full request/response schema for every endpoint.
  </Card>
</CardGroup>


# Agent Cards
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 log in, save a card, verify it for agentic use, set spending rules, and allow an agent to pay — the agent receives a secure one-time card number, expiration, and CVC.

<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**

  You can currently use agent cards with Mastercard and eligible U.S.-issued Visa credit and debit cards.

  **Not supported for Visa:** non-US cards, business cards, prepaid cards, Chase cards, Fidelity cards.

  For AMEX and Ramp cards, [contact us](https://www.crossmint.com/contact).
</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 five 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. **Register an agent.** Click **Create agent** to get an `agentId` — the handle every agent card is bound to.
3. **Save a card.** The `CrossmintPaymentMethodManagement` component collects the card in a PCI-compliant iframe and returns a `paymentMethodId`.
4. **Verify the card for agentic use.** A one-time email code + passkey ceremony links the saved card to the agent card rails. This is what authorizes agents to pay with the card — saving alone is not enough.
5. **Set spending rules and allow payment.** An **order intent** is created with two **spending rules**: `maxAmount` of 150 USD per `weekly` period and a free-text `description`. The user taps their passkey to authorize the spend, the app fetches credentials with the merchant info, and the secure one-time **card number, expiration, and CVC** are displayed.

## 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>


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

Why agents need both cards and stablecoin wallets, how spending rules keep them safe, and how one Checkout API buys from any merchant.

Agents operate across two distinct economies:

* **The traditional web runs on cards**. Amazon, Shopify stores, SaaS checkouts, and most traditional merchants rely on card payments. Users expect familiar properties like card rewards, refunds, and chargebacks.

* **The agentic web runs on stablecoins**. x402 and MPP-gated APIs, micropayments, and machine-to-machine settlement require stablecoins. Cards don’t work here since fees, chargebacks, and merchant account constraints make small or programmatic payments impractical.

Most agents need both, so **Crossmint provides cards and stablecoin wallets as first-class primitives.** Making an agent pay well comes down to two things: giving it **spending power under rules your users control**, and **routing each payment to the right destination**.

## Spending power & rules

You cannot give an agent unrestricted access to money:

* Credentials can be leaked
* Agents can overspend or behave unexpectedly

An agent with unlimited access is a liability. The goal is not just "agents can pay", it is "agents can pay securely without exposing sensitive data." Each instrument enforces this differently:

* **Cards.** The user’s real card is stored in a PCI-compliant vault. Users give agents **permissions** to use their card with spending rules (amount, merchant, duration), enforced at the network level via Visa VIC and Mastercard Agent Pay. The agent never sees the real card number — developers **never** handle sensitive information.

  Each agent card has two time dimensions: the **period** controls how often the spending limit resets (for example, weekly or monthly), while the **expiry** (`expiresAt`) controls when the permission itself stops working. These are independent — a monthly spending limit does not automatically keep the permission alive for a month. If no expiry is set, the permission defaults to seven days. See [Create an Agent Card](/agents/payment-methods/cards/create-agent-card) for details.

* **Stablecoin wallets.** The user owns a non-custodial wallet and grants the agent scoped permissions (spend limit, counterparties, time window), enforced onchain. Developers and agents never take custody of funds.

<Frame type="simple">
  <img alt="Diagram: a user verifies their card once via Visa VIC or Mastercard Agent Pay, and agents receive scoped permissions with spending rules" />

  <img alt="Diagram: a user verifies their card once via Visa VIC or Mastercard Agent Pay, and agents receive scoped permissions with spending rules" />
</Frame>

Every instrument is set up through a **user flow** — a hosted, customizable UI where the user explicitly delegates access. Every delegation is explicit, scoped, and revocable, so the user stays in control. Crossmint provides the UI components and signing flows; you wire them into your product.

<Tabs>
  <Tab title="Cards">
    <Steps>
      <Step title="User saves a card">
        Via a Crossmint-hosted secure iframe.
      </Step>

      <Step title="User verifies the card for agentic use">
        This step links the card to the agent card rails.

        * Happens in a Crossmint component
        * User verifies ownership (e.g. email code or bank auth)
        * A passkey is created for future approvals
      </Step>

      <Step title="The user sets spending rules and allows payment">
        The developer requests an agent card with spending rules (amount, merchant, expiration). A network modal (Visa/Mastercard) appears and the user confirms using their passkey.
      </Step>

      <Step title="Agent pays using a secure card number">
        Each approved payment returns a **secure one-time card number** that only works within the spending rules — never the real card number. The agent uses it in checkout or APIs.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Stablecoin wallets">
    <Steps>
      <Step title="User creates and funds a non-custodial wallet">
        Created via the Crossmint SDK. The user retains ownership — Crossmint and the developer never take custody. Funded by direct transfer or fiat onramp.
      </Step>

      <Step title="User delegates scoped access to the agent">
        The agent gets its own key and is added as a **signer** on the user's wallet, bound to a permission set the user signs off on:

        * **Spend cap** — max amount the agent can move
        * **Allowed counterparties** — addresses or protocols the agent can interact with
        * **Time window** — when the delegation is valid

        Permissions are enforced onchain. The user can revoke at any time.
      </Step>

      <Step title="Agent transacts autonomously within scope">
        The agent signs and submits transactions with its own key — no user prompt per action. Anything outside the delegated scope is rejected at the wallet level.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Where agents spend

Once an agent has funded, rule-bound spending power, a payment still has to reach its destination. The right rail depends on *where* it is paying.

### Machine-native payments

To pay APIs and other agents, the agent settles in stablecoins directly:

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

### Merchant checkout

Buying from a real merchant is the hard part. Today an agent has three options, and each falls short:

* **Buy through the merchant's API — if one exists.** Most merchants have no way to purchase programmatically at all.
* **Use an emerging agentic commerce protocol (UCP, ACP, …).** These help where a merchant has adopted one, but they typically hand back a checkout link rather than completing the payment — and most merchants haven't adopted any of them yet.
* **Drive a browser yourself.** This works anywhere, but it's slow and expensive: with today's frontier models a single checkout can burn several dollars in tokens, and a hand-rolled agent isn't optimized for it.

**[Agent Checkouts](/agents/agent-checkouts-quickstart) unifies all three behind one API — and makes it cheap.** Hand it a product and a spending cap, and it:

* **Picks the right rail per merchant** — an agentic commerce protocol where one exists, and an **optimized browser session** as the universal fallback everywhere else. Crossmint runs and tunes that session, so you're not paying frontier-model prices to drive a browser on every purchase.
* **Completes the payment, not just the cart** — end to end, with any method the merchant accepts: a Crossmint Agent Card, another agent-card provider (Ramp, Link, …), a card already on file from a logged-in account, or a local method like Shop Pay, bank transfer, or Bizum.
* **Stays within your spending rules** — you set a hard cap and the checkout never spends above it.

The result: your agent can buy anything, anywhere — without wiring up a separate integration per merchant, or burning dollars in tokens per checkout.

## Choose your path

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

  <Card title="Wallets quickstart" icon="wallet" href="/agents/stablecoin-wallet-quickstart">
    Build 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>


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

Payment infrastructure for AI agents

Enable agents to **pay for 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 being PCI-compliant.

Three products make it happen, each usable on its own and built to compose:

1. **Agent Cards:** a card for your agent to pay with, secured by Visa VIC and Mastercard Agent Pay.
2. **Agent Wallets:** a non-custodial wallet for stablecoin micropayments via x402 and MPP.
3. **Agent Checkouts:** one API to buy from any merchant. Supports any payment method the merchant supports, from Crossmint Agent Cards or any other agent card solution (e.g. Ramp Agent Cards), to saved cards in your account, Shop Pay, bank transfer, Bizum, etc.

## Payment methods

How agents hold spending power, under rules your users set and can revoke.

<CardGroup>
  <Card title="Agent Cards" icon="credit-card" href="/agents/cards-quickstart">
    Scoped, user-approved card spending, secured at the network level.
  </Card>

  <Card title="Agent Wallets" icon="wallet" href="/agents/stablecoin-wallet-quickstart">
    Non-custodial wallets with scoped agent spending access.
  </Card>
</CardGroup>

## Payment flows

How agents actually move money — across merchant checkouts, APIs, and machine-to-machine paths.

<CardGroup>
  <Card title="Agent Checkouts" icon="browser" href="/agents/agent-checkouts-quickstart">
    Buy from any merchant with any payment method it accepts.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="x402" icon="bolt" href="/agents/payment-flows/x402">
    Stablecoin micropayments, per API call.
  </Card>

  <Card title="MPP" icon="arrows-left-right" href="/agents/payment-flows/mpp">
    Agent-to-agent and service-to-service payments.
  </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>

<Card title="How agents pay" icon="diagram-project" href="/agents/how-agents-pay">
  The full mental model, payment methods, spending rules, and destinations.
</Card>


# Buy from Authenticated Stores
Source: https://docs.crossmint.com/agents/payment-flows/agent-checkouts-authenticated-stores

Let the agent sign in to the user's account at a merchant to use saved addresses, saved payment methods, and account pricing.

Some purchases only work when you're **logged in** to the merchant: a saved cart, member pricing, subscription reorders, or a card and address already stored on the account. **Authenticated stores** let the agent check out inside the user's signed-in session at the merchant, rather than as a guest.

With an authenticated session, the agent can:

* Use the user's **saved payment methods** — a card already on file at the merchant, so there's no card for you to submit.
* Use **saved addresses** and account defaults.
* See **account-specific pricing**, carts, and eligibility.

This is what makes "pay with a card on file" (see [Choose a Payment Method](/agents/payment-flows/agent-checkouts-payment-method)) possible: the payment method lives in the merchant account, and the agent selects it during the logged-in checkout.

<Warning>**Closed beta.** Buying from authenticated stores is in closed beta and enabled per project. [Reach out to Crossmint](https://www.crossmint.com/contact/sales) to request access.</Warning>


# Provide Purchase Context
Source: https://docs.crossmint.com/agents/payment-flows/agent-checkouts-buyer-context

Give the agent the buyer's identity, shipping, and intent so it can check out without stopping to ask.

By default, an Agent Checkout stops and asks about **every decision the merchant's checkout involves** — the buyer's name and shipping address, any merchant-specific prompt (buying flowers? it will ask what note to put on the card), and payment. Each one comes back to you as a **user action** to answer mid-run.

You can pre-answer most of them by writing the context up front — a reusable **buyer profile** and a per-checkout **buyer request** — and the agent uses what you provide instead of asking. The one thing you can't pre-supply is **card details**: the agent always collects those through a user action, though you can still choose the payment *method* in the request (see [Choose a Payment Method](/agents/payment-flows/agent-checkouts-payment-method)).

## Buyer profiles

A **buyer profile** is a reusable, saved set of the buyer's **name, contact, and shipping address**. It holds **no payment data** — payment is always handled per checkout (see [Choose a Payment Method](/agents/payment-flows/agent-checkouts-payment-method)).

Save a profile once, then attach it to any checkout with `buyerProfileId`. The agent prefills identity and shipping fields from it instead of asking every time — ideal when the same user checks out repeatedly.

```typescript theme={null}
// Create once
const { id: buyerProfileId } = await (
    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", // ISO 3166-2, country-prefixed
                postalCode: "94105",
                countryCode: "US", // ISO 3166-1 alpha-2
            },
        }),
    })
).json();

// Reuse on every checkout
await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({ target: { kind: "direct_url", url }, buyerProfileId, constraints }),
});
```

Profiles are managed through the buyer-profile endpoints (create, list, get, update, delete) and need the `agent-checkouts.buyer-profiles.*` scopes on your key. See the [API Reference](/api-reference/agent-checkouts/create-buyer-profile) for the full schema.

## The buyer request

The **buyer request** (`target.request`) is a per-checkout, natural-language instruction describing **what to buy and how**. It's where you steer this specific purchase: variant, size, quantity, delivery option, billing preference, and which payment method to use.

The more you specify, the fewer pending actions the agent raises. Say nothing and it will stop to ask about each decision; a fully specified request can run start to finish:

```typescript theme={null}
target: {
    kind: "direct_url",
    url: "https://merchant.example/products/classic-tee",
    request: "buy size M in black, cheapest delivery, billing same as shipping",
}
```

**You can name the payment method here, but not the card details.** Say which method to use (e.g. "pay by card") in the request; the agent still collects the actual card details through a payment user action during the run. Read [Choose a Payment Method](/agents/payment-flows/agent-checkouts-payment-method) for how that works.

<Info>**Profile vs. request.** The buyer profile is reusable identity and shipping that rarely changes. The request is the per-purchase intent and preferences. Use a profile so you don't re-enter the buyer's details, and the request to describe each order.</Info>

## Next

<Card title="Choose a Payment Method" icon="credit-card" href="/agents/payment-flows/agent-checkouts-payment-method">
  How the agent pays — supported methods, and how to pass a card safely.
</Card>


# Improve Merchant Success Rate
Source: https://docs.crossmint.com/agents/payment-flows/agent-checkouts-merchant-prompt

Use merchantContext to steer the agent through unusual checkouts that don't follow the standard add-to-cart flow.

For a standard store — add to cart, go to cart, proceed to checkout, enter shipping and payment — the agent already knows the pattern and handles it on its own. You **don't** need `merchantContext` there.

`merchantContext` is for the **unusual checkouts** that don't follow that pattern: a site with no cart, its own vocabulary, or a path to pay the agent wouldn't guess. It's a free-text field where you tell the agent exactly how to get through *this* site.

## When to use it

Reach for it when the flow isn't standard e-commerce — for example:

* **There's no cart.** Paying a medical bill, an invoice, or a utility account has no "add to cart" → "checkout" — the agent has to find a "Pay" or "Make a payment" action instead.
* **The site uses its own vocabulary.** The buttons aren't labeled "Add to cart", "Checkout", or "Place order", so the agent can't rely on the usual cues.
* **The path to pay is non-obvious.** The agent first has to enter an account or invoice number, choose a specific option, or click through a step it wouldn't guess on its own.

## How to use it

Pass `merchantContext` on `target`. Where `request` says **what to buy or pay**, `merchantContext` says **exactly what to click** on this site.

```typescript theme={null}
target: {
    kind: "direct_url",
    url: "https://provider.example/patient/billing",
    request: "pay the outstanding balance for account 4839221",
    merchantContext: [
        "This is a medical bill portal — there is no cart or 'add to cart'.",
        "Enter the account number in the 'Account #' field, then click 'Look up balance'.",
        "Click 'Pay now', choose 'Pay full balance', then continue to the payment form.",
    ].join(" "),
}
```

It's free text (up to 4,000 characters). Write it the way you'd brief a person doing this checkout for the first time — name the exact buttons and the order of steps. Skip anything the agent already handles, like filling standard forms or a normal cart-to-checkout flow.


# Choose a Payment Method
Source: https://docs.crossmint.com/agents/payment-flows/agent-checkouts-payment-method

Agent Checkouts can pay with any method the merchant accepts — Crossmint Agent Cards, other providers, cards on file, or local methods.

Because Agent Checkouts drives the merchant's real checkout, it can pay with **any method that merchant accepts** — not just a Crossmint card. That includes:

* **Crossmint Agent Cards** — a card you issue and control with [spending rules](/agents/how-agents-pay).
* **Other agent-card providers** — an agent card from another issuer, such as **Ramp Agent Cards**, **Link**, and others.
* **A card on file** — a card already saved in the user's account at the merchant, used by [logging into the store](/agents/payment-flows/agent-checkouts-authenticated-stores).
* **Local and alternative methods** — whatever the merchant offers at checkout, like **Shop Pay**, **bank transfer**, or **Bizum**.

## How payment is collected

Choose the payment **method** in the buyer [`request`](/agents/payment-flows/agent-checkouts-buyer-context) (e.g. `"pay by card"`) so the agent knows what to use. The **card details** are the one thing you can't put in the request — the agent collects those through a **user action**: when the checkout reaches the payment step it raises a `pendingUserAction`, and you submit the details in your response during the run.

## Which card to submit

When you submit card details in the payment action, use **only an agent card or a single-use / virtual card number — never a real, reusable card number (PAN)**. A scoped or one-time number can't be reused if it leaks; a reusable PAN can be charged again, so never send one.

This is why submitting such a number is fine: the card networks put single-use and virtual numbers **outside PCI-DSS scope** precisely because they can't be reused.

* **Visa:** single-use virtual Visa account numbers are *"out of scope for PCI DSS protection requirements based on the low risk of fraud,"* and EMVCo payment tokens *"are not considered to be Visa account data and are not in scope for PCI DSS"* — while *"all other Visa primary account numbers (PANs) must be protected in accordance with PCI DSS"* ([Expanded Position on PCI DSS Applicability for Virtual Visa Accounts](https://usa.visa.com/dam/VCOM/global/support-legal/documents/expanded-pci-dss.pdf)).
* **Mastercard:** Single-Use Virtual Card Numbers are treated as out of PCI-DSS scope because the number is disabled after one authorization and cannot be reused ([Virtual Card Numbers and SDP Compliance FAQs](https://www.mastercard.com/content/dam/public/mastercardcom/globalrisk/pdf/Virtual%20Card%20Numbers%20and%20SDP%20Compliance%20FAQs%20\(15%20February%202022\).pdf)).

The agent-card programs that issue these scoped tokens are [Visa Intelligent Commerce](https://developer.visa.com/capabilities/visa-intelligent-commerce) and [Mastercard Agent Pay](https://www.mastercard.com/us/en/business/artificial-intelligence/mastercard-agent-pay.html).

<Warning>Never submit a real, reusable card number (PAN). Use an agent card or a single-use / virtual number.</Warning>


# Create Checkouts Server-Side
Source: https://docs.crossmint.com/agents/payment-flows/agent-checkouts-server-side

Create checkouts from your backend with a server key — no user JWT — for an agent that buys for itself.

The [quickstart](/agents/agent-checkouts-quickstart) runs in the browser with a **client** key and a user's JWT. If you're building a skill for **your own agent** — buying for the agent itself, not on behalf of signed-in end users — skip the JWT and call the API **server-side** with a **server key** (`sk_...`).

* Send only `X-API-KEY: sk_...` (no `Authorization` header). The key needs the same `agent-checkouts.*` scopes. Keep it secret — unlike the `ck_` key, it is not safe in the browser.
* Checkouts then run under a fixed **service subject** for your project — ideal for one agent that buys for itself.
* To create a checkout **on behalf of a specific user**, add the **`x-crossmint-user-id`** header. The subject is namespaced under your project (a server key can only address its own project's subjects); omit it and it falls back to the shared service subject.

```typescript theme={null}
const res = await fetch("https://www.crossmint.com/api/unstable/agent-checkouts", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_SERVER_API_KEY, // sk_... — no JWT needed
        "x-crossmint-user-id": "user_123", // optional — act on behalf of a user; omit for the shared service subject
    },
    body: JSON.stringify({
        target: { kind: "direct_url", url: "https://merchant.example/products/classic-tee" },
        constraints: { maxCost: { amount: "100.00", currency: "USD" } },
    }),
});
```

Checkouts and buyer profiles are isolated per `(project, subject)`, so resources created under one `x-crossmint-user-id` are only visible to that subject. Everything else — polling, responding to actions, reading the receipt — works exactly as in the [quickstart](/agents/agent-checkouts-quickstart).


# 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 flow automatically.

## Prerequisites

* A Crossmint EVM wallet with USDC. See the [Wallets quickstart](/agents/stablecoin-wallet-quickstart).
* 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 payment 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 flow automatically.

## Prerequisites

* A Crossmint EVM wallet on Base with USDC. See the [Wallets quickstart](/agents/stablecoin-wallet-quickstart).
* 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>

## 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,
});

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>
</CardGroup>


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

Give an agent scoped permission to use a card with spending rules.

## Introduction

An agent card is created as an **order intent** — a request granting an agent scoped access to a card, defined by one or more **spending rules** (amount, description, frequency, and more).

The user authorizes the intent with their passkey, after which the permission becomes `active` and secure card numbers can be retrieved by the agent.

## Prerequisites

* A saved card that has been verified for agentic payments. See [Save a Card](/agents/payment-methods/cards/save-card) and [Verify a Card](/agents/payment-methods/cards/enroll-card) if you have not done this yet.
* The `agentId` from [Register an Agent](/agents/payment-methods/cards/register-agent).
* The `paymentMethodId` of the verified card.
* An authenticated user with a JWT.

<Note>
  **Eligible Cards**

  You can currently use agent cards with Mastercard and eligible U.S.-issued Visa credit and debit cards.

  **Not supported for Visa:** non-US cards, business cards, prepaid cards, Chase cards, Fidelity cards.

  For AMEX and Ramp cards, [contact us](https://www.crossmint.com/contact).
</Note>

## Steps

<Steps>
  <Step title="Create the order intent">
    Send a `POST` request to `/api/unstable/order-intents` with the agent, the card to charge, and one or more spending rules.

    ```typescript theme={null}
    const BASE_URL = "https://staging.crossmint.com/api/unstable";

    const response = await fetch(`${BASE_URL}/order-intents`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            agentId: agentId,
            payment: { paymentMethodId: paymentMethodId },
            mandates: [
                {
                    type: "maxAmount",
                    value: "150.00",
                    details: { currency: "usd", period: "monthly" },
                },
                {
                    type: "description",
                    value: "Weekly grocery purchases",
                },
            ],
            expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(), // 1 year from now
        }),
    });

    const orderIntent = await response.json();
    console.log(orderIntent.orderIntentId);
    console.log(orderIntent.phase);
    // "requires-verification" or "active"
    ```

    An agent card has two time controls. The mandate **`period`** (weekly, monthly, yearly) determines how often the spending limit resets. The **`expiresAt`** field determines when the permission itself stops working — after this date, the agent can no longer use it regardless of remaining balance. If `expiresAt` is not provided, it **defaults to seven days** from creation. Set `expiresAt` to a date that matches your use case — for example, a monthly spending limit typically needs an expiry at least one month in the future.

    For the full list of supported spending rule types and their fields, see the [Create Order Intent API Reference](/api-reference/agentic-commerce/order-intents/create-order-intent).

    **What to persist**

    | Data                                               | When                                                                                                                                      |
    | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | `orderIntentId`                                    | Always — every later operation keys off of it.                                                                                            |
    | `expiresAt`                                        | Always — track the expiry so you can create a new order intent before the permission lapses.                                              |
    | Merchant descriptor (`name`, `url`, `countryCode`) | When the card will charge the same merchant repeatedly. You pass it on every credential fetch, so saving it once avoids re-collecting it. |
    | Card credentials                                   | Never — short-lived and merchant-scoped. Fetch fresh on each purchase.                                                                    |
  </Step>

  <Step title="Authorize the intent via passkey">
    If the order intent's `phase` is `requires-verification`, the user must authorize the spending with their passkey. Use the `OrderIntentVerification` component:

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

    function AuthorizeSpending({ orderIntent }: { orderIntent: any }) {
        return (
            <OrderIntentVerification
                orderIntent={orderIntent}
                onVerificationComplete={() => {
                    console.log("Permission is now active");
                }}
                onVerificationError={() => {
                    console.error("Spending authorization failed");
                }}
            />
        );
    }
    ```

    This step is **passkey-only**. The user does not receive an email code — the one-time email verification was completed during enrollment, and the device is already bound.

    After `onVerificationComplete` fires, the order intent's phase changes to `active` and the permission is ready — secure card numbers can now be retrieved.
  </Step>
</Steps>

An order intent moves through `requires-verification` → `active` → `expired`. For the full phase semantics, see the [Get Order Intent API Reference](/api-reference/agentic-commerce/order-intents/get-order-intent).

<Accordion title="Example Response">
  ```json theme={null}
  {
      "orderIntentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phase": "requires-verification",
      "payment": {
          "paymentMethodId": "pm_abc123"
      },
      "mandates": [
          {
              "type": "maxAmount",
              "value": "150.00",
              "details": { "currency": "usd", "period": "monthly" }
          },
          {
              "type": "description",
              "value": "Weekly grocery purchases"
          }
      ],
      "expiresAt": "2030-01-01T00:00:00Z",
      "verificationConfig": {
          "environment": "test",
          "publicApiKey": "YOUR_PUBLIC_API_KEY",
          "agentId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "instructionId": "instr_xyz789"
      }
  }
  ```
</Accordion>

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

## Common Gotchas

<AccordionGroup>
  <Accordion title="Card permission requires a verified card">
    If the `paymentMethodId` has not been verified for agentic use, the order intent creation call will fail. Confirm `status: "active"` on the verification before creating an order intent.
  </Accordion>

  <Accordion title="Permission expires after seven days by default">
    If you do not pass `expiresAt` when creating the order intent, the permission defaults to seven days from creation. This applies regardless of the mandate `period` (weekly, monthly, or yearly). Always set `expiresAt` explicitly when the permission should remain valid beyond seven days.
  </Accordion>

  <Accordion title="Each new order intent needs a fresh passkey tap">
    Unless the response returns `phase: "active"` immediately, do not reuse a previous verification — each order intent has its own authorization.
  </Accordion>

  <Accordion title="Treat `onVerificationError` distinctly from `onVerificationComplete`">
    A denied or failed verification leaves the order intent in `requires-verification`. Do not attempt to fetch credentials until the phase is `active`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Retrieve Secure Card Numbers" icon="key" href="/agents/payment-methods/cards/retrieve-agent-card">
    Fetch a secure one-time card number, expiration, and CVC to complete a purchase.
  </Card>

  <Card title="Remove Cards" icon="trash" href="/agents/payment-methods/cards/remove-cards">
    Remove saved cards, delete agents, or rotate an agent card.
  </Card>
</CardGroup>


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

Style the card verification and spending authorization modals to match your brand.

## Overview

The card enrollment and spending authorization flows render a verification modal (passkey prompt) to the user. You can customize the look and feel of this modal using the `appearance` prop, which both verification components accept.

* **`PaymentMethodAgenticEnrollmentVerification`**: One-time card enrollment step. Shown when an enrollment's status is `"pending"` and needs passkey verification.
* **`OrderIntentVerification`**: Spending authorization step. Shown when an order intent's phase is `"requires-verification"`.

## How to customize the appearance

The 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 (e.g. `"14px"`). Title, small, error, input, and passkey sizes scale proportionally |
    | `spacingUnit`                | Base section spacing (e.g. `"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>

## Example

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

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

<OrderIntentVerification
    orderIntent={orderIntent}
    appearance={{
        variables: {
            colors: {
                accent: "#6366f1",
                backgroundPrimary: "#1e1e2e",
            },
        },
    }}
    onVerificationComplete={() => {}}
    onVerificationError={(err) => console.error(err)}
/>
```

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.


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

Authorize a saved card for agentic use with a one-time device-binding ceremony.

## Introduction

A saved card is not automatically usable by agents. Before agents can use it to pay, the card must be **verified for agentic payments**. Verification is a one-time step per card that produces two things:

1. **Account verification** via a one-time code sent to the user's email.
2. **A passkey bound to the user's device**, so future payment authorizations only need a single passkey tap.

Once a card is verified, every subsequent agent card can be authorized by the user with their passkey alone. The email step is not repeated.

## Prerequisites

* A saved card. See [Save a Card](/agents/payment-methods/cards/save-card) if you have not done this yet.
* The `paymentMethodId` of the saved card.
* An authenticated user with a JWT.

<Note>
  **Eligible Cards**

  You can currently use agent cards with Mastercard and eligible U.S.-issued Visa credit and debit cards.

  **Not supported for Visa:** non-US cards, business cards, prepaid cards, Chase cards, Fidelity cards.

  For AMEX and Ramp cards, [contact us](https://www.crossmint.com/contact).
</Note>

## Steps

<Steps>
  <Step title="Check the card's current verification status">
    Before starting verification, check whether the card is already verified. The API returns a `status` that is always one of the following:

    | Status        | Meaning                                                                                               |
    | :------------ | :---------------------------------------------------------------------------------------------------- |
    | `not_started` | Verification has not been started yet.                                                                |
    | `pending`     | Verification was started; the user still needs to complete the challenge (email code and/or passkey). |
    | `active`      | Verification finished; the card is ready for agent agent cards.                                       |

    ```typescript theme={null}
    const BASE_URL = "https://staging.crossmint.com/api/unstable";

    async function checkEnrollment(jwt: string, paymentMethodId: string) {
        const response = await fetch(
            `${BASE_URL}/payment-methods/${paymentMethodId}/agentic-enrollment`,
            {
                headers: {
                    "Content-Type": "application/json",
                    "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
                    Authorization: `Bearer ${jwt}`,
                },
            }
        );

        return response.json();
        // { status: "active" | "pending" | "not_started", ... }
    }
    ```

    If the status is `active`, verification is complete and you can skip directly to [Create an Agent Card](/agents/payment-methods/cards/create-agent-card). If it is `pending`, reuse the existing verification response in the next step rather than creating a new one.
  </Step>

  <Step title="Start verification">
    If the card is `not_started`, send a `POST` request with the user's email to begin verification. The response includes an `enrollmentId` and a `verificationConfig` that the verification component uses to run the passkey ceremony.

    ```typescript theme={null}
    async function startEnrollment(
        jwt: string,
        paymentMethodId: string,
        email: string
    ) {
        const response = await fetch(
            `${BASE_URL}/payment-methods/${paymentMethodId}/agentic-enrollment`,
            {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
                    Authorization: `Bearer ${jwt}`,
                },
                body: JSON.stringify({ email }),
            }
        );

        return response.json();
    }
    ```

    Example response:

    ```json theme={null}
    {
        "enrollmentId": "enr_abc123",
        "status": "pending",
        "verificationConfig": {
            "environment": "test",
            "publicApiKey": "YOUR_PUBLIC_API_KEY"
        }
    }
    ```
  </Step>

  <Step title="Render the verification component">
    Pass the pending verification response to the `PaymentMethodAgenticEnrollmentVerification` component. It runs the full device-binding ceremony inside your UI — the user receives an email code, enters it, and then creates a passkey bound to the current device.

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

    function EnrollCardStep({ enrollment }: { enrollment: PendingEnrollment }) {
        return (
            <PaymentMethodAgenticEnrollmentVerification
                enrollment={enrollment}
                onVerificationComplete={() => {
                    console.log("Card is now verified for agentic use");
                }}
                onVerificationError={(error) => {
                    console.error("Verification failed", error);
                }}
            />
        );
    }
    ```

    When `onVerificationComplete` fires, the server has flipped the verification to `active`. The card is now ready for agent agent cards.
  </Step>
</Steps>

## Understanding the Verification Flow

The `PaymentMethodAgenticEnrollmentVerification` component runs the following sequence in order:

1. The server sends a one-time code to the user's email.
2. The user enters the code in the component's UI.
3. The component prompts the browser to create a passkey bound to this device.
4. The server marks the verification `active`.

**The email code and the passkey are not two separate checks.** The email code proves the user owns the account; the passkey then binds the device so that future payment authorizations can skip the email step. Both are part of a single device-binding ceremony.

## Common Gotchas

<AccordionGroup>
  <Accordion title="The email step only happens during verification">
    Once a card is verified, all subsequent payment authorizations use the passkey alone. If you see the email code prompt on a non-verification flow, the device is not yet bound — complete verification first.
  </Accordion>

  <Accordion title="A passkey is bound to a single device and browser profile">
    If the user clears browser state, switches browsers, or moves to a new device, they may be asked to re-verify for future actions on that new device.
  </Accordion>

  <Accordion title="Verification is per payment method, not per agent">
    Once a card is verified, any agent on the account can be given agent cards from it.
  </Accordion>
</AccordionGroup>

## What Is Next

With the card verified, the last step in this setup path is to [Create an Agent Card](/agents/payment-methods/cards/create-agent-card) so your agent can pay within scoped spending rules against the verified payment method.


# Register an Agent
Source: https://docs.crossmint.com/agents/payment-methods/cards/register-agent

Authenticate a user and create an agent identity for the cards flow.

This guide covers the first two steps of the cards flow: authenticating a user to obtain a JWT, then registering an **agent** that can pay on their behalf. By the end you will have an `agentId` to use in every subsequent step.

## Prerequisites

* **Crossmint API key** — a client-side key from the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Console</a>. In staging, all scopes are enabled by default.
* **Authentication provider** — any provider that issues JWTs your backend can verify (for example <a href="https://stytch.com/">Stytch</a>, Auth0, Dynamic, or [Crossmint Auth](/authentication/introduction)). The <a href="https://github.com/Crossmint/card-permissions-quickstart">card-permissions-quickstart</a> uses Stytch with Google OAuth.

## Step 1: Authenticate the User

Before calling any Crossmint endpoint you need a valid session JWT for the user. How you obtain it depends on your auth provider. Below is the pattern used by the quickstart with Stytch:

```typescript theme={null}
import { useStytch } from "@stytch/nextjs";
import { useCrossmint } from "@crossmint/client-sdk-react-ui";

function useAuthSetup() {
    const stytch = useStytch();
    const { setJwt } = useCrossmint();

    // After the user completes login (e.g. Google OAuth redirect):
    const tokens = stytch.session.getTokens();
    const jwt = tokens?.session_jwt ?? "";

    // Bridge the JWT to the Crossmint SDK so it can authenticate requests
    setJwt(jwt);

    return jwt;
}
```

The key requirement is that every Crossmint API call includes:

* `X-API-KEY` header with your Crossmint client API key
* `Authorization: Bearer <jwt>` header with the user's session JWT

If you are using a different auth provider, replace the Stytch calls above with your provider's equivalent. See [Identity and Auth](/authentication/introduction) for more options.

## Step 2: Register an Agent

With the JWT in hand, send a `POST` request to `/api/unstable/agents` to create an agent for this user.

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(`${BASE_URL}/agents`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        metadata: {
            name: "Card Payment Agent",
            description: "Default agent for card payments",
        },
    }),
});

const agent = await response.json();
console.log(agent.agentId); // e.g. "d290f1ee-6c54-4b01-90e6-d701748f0851"
```

Store the `agentId` — you will pass it when saving cards, setting up agent cards, and fetching secure card numbers. You typically create **one agent per user**.

For the full request and response schema, see the [Create Agent API Reference](/api-reference/agentic-commerce/agents/create-agent).

<AccordionGroup>
  <Accordion title="Example Response">
    ```json theme={null}
    {
      "agentId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "metadata": {
        "name": "Card Payment Agent",
        "description": "Default agent for card payments"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## What Is Next

Now that you have an authenticated user and a registered agent, the next step is to [Save a Card](/agents/payment-methods/cards/save-card) so the agent can be given permission to pay with it.


# Remove Cards
Source: https://docs.crossmint.com/agents/payment-methods/cards/remove-cards

Remove saved cards, delete agents, and rotate agent cards.

## Introduction

This page covers the independent lifecycle operations for the cards flow. Pick the section that matches what you need to do — each operation is self-contained.

| If you need to…                                              | See                                           |
| ------------------------------------------------------------ | --------------------------------------------- |
| Stop a saved card from being used for any future agent cards | [Remove a saved card](#remove-a-saved-card)   |
| Cut off an agent's ability to create new agent cards         | [Delete an agent](#delete-an-agent)           |
| Immediately invalidate a single active agent card            | [Revoke an agent card](#revoke-an-agent-card) |
| Replace an agent card whose credentials may be compromised   | [Rotate an agent card](#rotate-an-agent-card) |

## Prerequisites

* An authenticated user with a valid JWT.
* The ID of the resource you want to modify (`paymentMethodId` for a card, `agentId` for an agent).

## Remove a Saved Card

Send a `DELETE` request with the `paymentMethodId`. The card can no longer be used to create new agent cards.

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

async function removePaymentMethod(jwt: string, paymentMethodId: string) {
    const response = await fetch(
        `${BASE_URL}/payment-methods/${paymentMethodId}`,
        {
            method: "DELETE",
            headers: {
                "Content-Type": "application/json",
                "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
                Authorization: `Bearer ${jwt}`,
            },
        }
    );

    if (!response.ok) {
        throw new Error(`Failed to remove payment method (${response.status})`);
    }
}
```

<Note>
  Removing a saved card does **not** cancel agent cards already created against it. Active order intents keep working until their internal expiration is reached. To cut off an in-flight order intent immediately, [revoke it](#revoke-an-agent-card) or delete the agent.
</Note>

## Delete an Agent

Send a `DELETE` request with the `agentId`. The agent loses the ability to create new agent cards, and any active order intents tied to it stop working.

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

async function deleteAgent(jwt: string, agentId: string) {
    const response = await fetch(
        `${BASE_URL}/agents/${agentId}`,
        {
            method: "DELETE",
            headers: {
                "Content-Type": "application/json",
                "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
                Authorization: `Bearer ${jwt}`,
            },
        }
    );

    if (!response.ok) {
        throw new Error(`Failed to delete agent (${response.status})`);
    }
}
```

<Warning>
  Deletion is permanent. To restore the agent's ability to spend, register a new agent by following [Register an Agent](/agents/payment-methods/cards/register-agent).
</Warning>

## Revoke an Agent Card

To immediately invalidate a single agent card — for example if its credentials may have been compromised — send a `DELETE` request with the `orderIntentId`. The order intent transitions to the `revoked` phase and its credentials can no longer be used for purchases.

Only order intents currently in the `active` or `requires-verification` phase can be revoked. Already-`expired` or already-`revoked` order intents return an error.

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

async function revokeOrderIntent(jwt: string, orderIntentId: string) {
    const response = await fetch(
        `${BASE_URL}/order-intents/${orderIntentId}`,
        {
            method: "DELETE",
            headers: {
                "Content-Type": "application/json",
                "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
                Authorization: `Bearer ${jwt}`,
            },
        }
    );

    if (!response.ok) {
        throw new Error(`Failed to revoke order intent (${response.status})`);
    }
}
```

A successful revoke returns `204 No Content`. The underlying saved card and agent are untouched — only the targeted order intent is affected. To replace it with a new agent card, see [Rotate an agent card](#rotate-an-agent-card).

For the full schema, see the [Revoke Agent Card API Reference](/api-reference/agentic-commerce/order-intents/revoke-order-intent).

## Rotate an Agent Card

To rotate an agent card — for example if its credentials may have been compromised — revoke the old order intent and create a replacement:

1. [Revoke](#revoke-an-agent-card) the old order intent so its credentials can no longer be used.
2. Create a new order intent against the same saved card with the same (or updated) spending rules. See [Create an Agent Card](/agents/payment-methods/cards/create-agent-card).
3. Have the user authorize the new intent via passkey.
4. Use the new credentials in your checkout flow.

```typescript theme={null}
await revokeOrderIntent(jwt, oldOrderIntentId);

// Create a replacement agent card against the same payment method
const newOrderIntent = await createOrderIntent(jwt, agentId, paymentMethodId, mandates);

// If requires-verification, prompt the user for passkey authorization,
// then fetch credentials for the new card
const newCredentials = await fetchCardCredentials(jwt, newOrderIntent.orderIntentId, merchant);
```

<Note>
  To cut off an agent's access to **all** of its agent cards immediately, [delete the agent](#delete-an-agent) instead. For the full list of order intent phases — including `revoked` and `expired` — see the [Get Order Intent API Reference](/api-reference/agentic-commerce/order-intents/get-order-intent).
</Note>

## Next Steps

<CardGroup>
  <Card title="Create an Agent Card" icon="credit-card" href="/agents/payment-methods/cards/create-agent-card">
    Set up a new scoped agent card with updated spending rules.
  </Card>

  <Card title="Register an Agent" icon="robot" href="/agents/payment-methods/cards/register-agent">
    Create a new agent after deleting one.
  </Card>
</CardGroup>


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

Fetch a secure one-time card number, expiration, and CVC for an active agent card.

## Introduction

Retrieving secure card numbers is the final step in the cards flow. Once an order intent is `active`, you exchange the `orderIntentId` and a merchant descriptor for a secure one-time card number, expiration, and CVC that the agent uses to complete the purchase.

Credentials are scoped to the merchant you specify, so they can only be used where the user authorized the spending. The agent never sees the real card number.

## Prerequisites

* An order intent with `phase: "active"`. See [Create an Agent Card](/agents/payment-methods/cards/create-agent-card) if you have not done this yet.
* The `orderIntentId` of the active order intent.
* An authenticated user with a JWT.

## Fetch Credentials

Send a `POST` request to `/api/unstable/order-intents/{orderIntentId}/credentials` with the merchant information. The merchant details are required so that Crossmint can generate credentials scoped to that specific merchant.

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(
    `${BASE_URL}/order-intents/${orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            merchant: {
                name: "Whole Foods",
                url: "https://www.wholefoodsmarket.com",
                countryCode: "US",
            },
        }),
    }
);

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

The response contains the secure card number details your agent needs to complete a purchase:

```json theme={null}
{
    "card": {
        "number": "4000056655665556",
        "expirationMonth": "12",
        "expirationYear": "2027",
        "cvc": "123"
    },
    "expiresAt": "2026-05-01T00:00:00Z"
}
```

### Merchant Fields

| Field         | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `name`        | Display name of the merchant                               |
| `url`         | The merchant's website URL                                 |
| `countryCode` | Two-letter ISO country code (for example `US`, `GB`, `DE`) |

The merchant descriptor must be passed on every credential fetch — it is not stored on the order intent. For recurring spend at a fixed merchant, persist these fields alongside the `orderIntentId` when you set up the agent card. See [What to persist](/agents/payment-methods/cards/create-agent-card#step-1) on the Create an Agent Card page for the full guidance.

## List Agent Cards

To see all agent cards (order intents) for the authenticated user, send a `GET` request to the order intents endpoint:

```typescript theme={null}
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(`${BASE_URL}/order-intents`, {
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
});

const orderIntents = await response.json();
// Returns an array of order intents with their phases and spending rules
```

Only order intents with `phase: "active"` can have their credentials fetched. Expired order intents return an error.

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

## Common Gotchas

<AccordionGroup>
  <Accordion title="Credentials are merchant-scoped">
    The `merchant` field is required on every credential request. A card number fetched for one merchant will not authorize at another — if the agent needs to spend at a different merchant, create a new agent card.
  </Accordion>

  <Accordion title="Credentials have their own `expiresAt`">
    Even within an `active` order intent, the returned card data is short-lived. Fetch credentials as close to the purchase as possible rather than caching them.
  </Accordion>

  <Accordion title="Fetching credentials before the phase is active fails">
    If the user has not yet completed the passkey authorization, wait for `onVerificationComplete` before calling this endpoint.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Remove Cards" icon="trash" href="/agents/payment-methods/cards/remove-cards">
    Remove saved cards, delete agents, or rotate an agent card.
  </Card>

  <Card title="Cards Quickstart" icon="credit-card" href="/agents/cards-quickstart">
    Revisit how credential retrieval fits into the full cards flow.
  </Card>
</CardGroup>


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

Tokenize a user's card via Crossmint's PCI-compliant UI so it can later be enrolled for agentic use.

## Introduction

Saving a card enables a physical card to be tokenized for agentic use and onramps. The user enters their card into a Crossmint-hosted UI, Crossmint tokenizes it in a PCI-compliant vault, and your app receives a `paymentMethodId` it can use in later flows to retrieve card details. Raw card data never reaches your servers.

Think of this like Apple Pay or a browser storing a card once so it can be used securely later — but with one important difference. **Saving a card does not authorize agents to use it.** Enrollment is a separate, explicit step covered in the next guide.

## Prerequisites

* A registered agent with a valid `agentId`. See [Register an Agent](/agents/payment-methods/cards/register-agent) if you have not done this yet.
* The user must be authenticated and you must have a JWT for them.

## 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 [Testing All Flows](#testing-all-flows).
    </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 }) => {
            // paymentMethod.paymentMethodId represents the saved card.
            // Persist it so you can verify the card and give agent cards later.
            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 initiate payment-related operations, including verification and agent card setup.
  </Step>
</Steps>

## Testing All Flows

In staging, the test card number determines how downstream flows behave — success, card-not-eligible, issuer decline, OTP challenges, and so on. Use these cards to exercise every branch of your integration without needing live cards or real issuers.

### Visa

| Card                  | Scenario                                              |
| --------------------- | ----------------------------------------------------- |
| `4242 4242 4242 4242` | Happy path — auto-approved, no passkey required       |
| `4000 0000 0000 0002` | Standard flow — OTP verification and passkey creation |
| `4000 0566 5566 5556` | Completes enrollment without passkey creation         |
| `4539 0978 8716 3333` | Card not eligible for agentic enrollment              |
| `4929 5442 4031 8920` | Declined by issuer during enrollment                  |
| `4000 0000 0000 3063` | `PROVIDER_ENROLLMENT_FAILED` — retryable              |
| `4000 0000 0000 3071` | Token provisioning failure — retryable                |
| `4330 2512 0750 6660` | `CARD_REJECTED` during network verification           |
| `4929 9803 9556 7582` | OTP submission always returns `INVALID_OTP`           |
| `4916 7252 9792 5395` | OTP submission returns `MAX_ATTEMPTS_EXCEEDED`        |

Use any future expiration date and any three-digit CVC.

## What Is Next

The `paymentMethodId` represents a saved card, but not yet a card that an agent can use. Before giving any agent cards, verify the card for agentic payments.

Continue to [Verify a Card](/agents/payment-methods/cards/enroll-card) to authorize this saved card for agent use through a one-time passkey verification step.


# 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 signer. 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 signer 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",
                            recovery: { 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="The recovery signer cannot be removed later">
    The signer chosen at creation time is the wallet's root. Agents are added on top as scoped delegates and can be revoked, but the root recovery signer is permanent.
  </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="x402 Payment Flow" 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

Let users fund their wallet with a credit card so the agent can spend from it.

## Introduction

Once a user wallet is created and the agent is authorized, the next step is to fund the wallet so the agent has stablecoins to spend. 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'll 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`:

    ```sh .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.

    ```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.
  </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.
  </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="On-Chain Actions" icon="paper-plane" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Once funded, send stablecoins and call contracts 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 signer, 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 signer (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 signer (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;

        // Activate the user's recovery signer — only the user can authorize removal
        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 signer can remove an agent">
    Calls to `wallet.removeSigner` must be made with the user's recovery signer 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. There is no recovery signer 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
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", recovery: { type: "email" } }}`, so a non-custodial smart wallet is created on first login with the user's email as the recovery signer. 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.

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>


# Get Usage
Source: https://docs.crossmint.com/api-reference/admin/get-usage

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

delete /unstable/agent-checkouts/{id}
Cancel an in-progress agent checkout.

**API scope required**: `agent-checkouts.cancel`



# Create Agent Checkout
Source: https://docs.crossmint.com/api-reference/agent-checkouts/create-agent-checkout

post /unstable/agent-checkouts
Start an agent checkout that drives a browser through a merchant checkout to purchase a product.

**API scope required**: `agent-checkouts.create`



# Create Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/create-buyer-profile

post /unstable/agent-checkouts/buyer-profiles
Creates a subject-scoped buyer profile (buyer identity + global shipping address) that the agent can prefill during a checkout run. Payment data is never stored. Returns the created profile.

**API scope required**: `agent-checkouts.buyer-profiles.create`



# Delete Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/delete-buyer-profile

delete /unstable/agent-checkouts/buyer-profiles/{id}
Deletes a buyer profile owned by the authenticated user. Checkouts that already ran with it keep their captured buyer-profile provenance.

**API scope required**: `agent-checkouts.buyer-profiles.delete`



# Get Agent Checkout
Source: https://docs.crossmint.com/api-reference/agent-checkouts/get-agent-checkout

get /unstable/agent-checkouts/{id}
Retrieve the current state of an agent checkout.

**API scope required**: `agent-checkouts.read`



# Get Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/get-buyer-profile

get /unstable/agent-checkouts/buyer-profiles/{id}
Retrieves a buyer profile owned by the authenticated user.

**API scope required**: `agent-checkouts.buyer-profiles.read`



# List Buyer Profiles
Source: https://docs.crossmint.com/api-reference/agent-checkouts/list-buyer-profiles

get /unstable/agent-checkouts/buyer-profiles
Lists the authenticated user's buyer profiles, newest first. Paginate with the opaque `cursor` taken from the previous page's `nextCursor`.

**API scope required**: `agent-checkouts.buyer-profiles.read`



# Respond to User Action
Source: https://docs.crossmint.com/api-reference/agent-checkouts/respond-to-action

post /unstable/agent-checkouts/{id}/actions/{actionId}
Submits or declines a pending user action on an agent checkout. The `actionId` is the `pendingUserAction.id` from the checkout view, supplied **in the path only** — including it in the body is rejected.

A `submit` must carry `values` that satisfy the action's `responseSchema`. The response is an acknowledgement; more actions may follow, so return to polling `GET /{id}` afterwards.

**API scope required**: `agent-checkouts.update`



# Update Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/update-buyer-profile

patch /unstable/agent-checkouts/buyer-profiles/{id}
Updates a buyer profile's writable fields. Provide any non-empty subset of `label`, `name`, `contact`, and `shipping`. `name` and `contact` are replaced wholesale; `shipping` is merged field-by-field.

**API scope required**: `agent-checkouts.buyer-profiles.update`



# Create Agentic Enrollment
Source: https://docs.crossmint.com/api-reference/agentic-commerce/agentic-enrollment/create-agentic-enrollment

post /unstable/payment-methods/{paymentMethodId}/agentic-enrollment
Create an agentic enrollment for a payment method.

**API scope required**: `payment-methods.create`

<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 Agentic Enrollment
Source: https://docs.crossmint.com/api-reference/agentic-commerce/agentic-enrollment/get-agentic-enrollment

get /unstable/payment-methods/{paymentMethodId}/agentic-enrollment
Get the agentic enrollment status of a payment method.

**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>


# Create Agent
Source: https://docs.crossmint.com/api-reference/agentic-commerce/agents/create-agent

post /unstable/agents
Create a new agent.

**API scope required**: `agents.create`



# Delete Agent
Source: https://docs.crossmint.com/api-reference/agentic-commerce/agents/delete-agent

delete /unstable/agents/{agentId}
Delete an agent.

**API scope required**: `agents.delete`



# List Agents
Source: https://docs.crossmint.com/api-reference/agentic-commerce/agents/list-agents

get /unstable/agents
List all agents for the authenticated user.

**API scope required**: `agents.read`



# Create Agent Card
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/create-order-intent

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

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

post /unstable/order-intents/{orderIntentId}/credentials
Get credentials for 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

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

delete /unstable/order-intents/{orderIntentId}
Revoke an active order intent, deleting its underlying instruction and disabling its virtual card credentials.

**API scope required**: `order-intents.revoke`



# Create Payment Method
Source: https://docs.crossmint.com/api-reference/agentic-commerce/payment-methods/create-payment-method

post /unstable/payment-methods
Create a new payment method.

**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

delete /unstable/payment-methods/{paymentMethodId}
Delete a payment method.

**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

get /unstable/payment-methods
List all payment methods for the authenticated user.

**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

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

GET /v1-alpha2/tokens/{tokenLocator}
Get a token by its locator



# Create Order
Source: https://docs.crossmint.com/api-reference/headless/create-order

post /2022-06-09/orders
Creates a new order that can be used to complete a headless checkout.

**API scope required**: `orders.create`




# Edit Order
Source: https://docs.crossmint.com/api-reference/headless/edit-order

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

get /2024-09-26/tokens
Retrieve a paginated list of all supported tokens for checkout. Sorted by most recent first.



# Get Order
Source: https://docs.crossmint.com/api-reference/headless/get-order

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

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

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

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 as it existed before deletion.


# Retrieve a Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/get-payment-method

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

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-mx-clabe`  | Mexican bank account, identified by an 18-digit CLABE.                   |
| `bank-account-co`        | Colombian bank account (bank code + account number + national document). |
| `bank-account-sepa-iban` | Bank account identified by an IBAN within the supported SEPA scope.      |

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

<ResponseField name="displayName" type="string">
  Human-readable label for the payment method (e.g. `"Visa ••1111"`, `"Chime ••6259"`).
</ResponseField>

<ResponseField name="type" type="string">
  Payment method type. One of `card`, `bank-account-us`, `bank-account-mx-clabe`, `bank-account-co`, or `bank-account-sepa-iban`.
</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-mx-clabe`, `bank-account-co`, or `bank-account-sepa-iban`.

  <Expandable title="common properties">
    <ResponseField name="billing" type="object">
      Billing details for the account holder.

      <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">
          <Expandable title="properties">
            <ResponseField name="line1" type="string" />

            <ResponseField name="line2" type="string" />

            <ResponseField name="city" type="string" />

            <ResponseField name="stateOrRegion" type="string" />

            <ResponseField name="postalCode" type="string" />

            <ResponseField name="country" type="string">
              ISO 3166-1 alpha-2 country code.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bankName" type="string | null">
      Name of the bank. `null` if not resolvable.
    </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="MX-specific properties (bank-account-mx-clabe)">
    <ResponseField name="bankCode" type="string">
      Three-digit bank code derived from the CLABE.
    </ResponseField>
  </Expandable>

  <Expandable title="CO-specific properties (bank-account-co)">
    <ResponseField name="bankCode" type="string">
      Bank code assigned by Banco de la República.
    </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>
</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 SEPA theme={null}
  {
    "paymentMethodId": "3323460b-d9d2-4ec6-b380-8a3e01e3f226",
    "default": false,
    "displayName": "SEPA Account ••6789",
    "type": "bank-account-sepa-iban",
    "bankAccount": {
      "billing": {
        "name": "Hans Müller",
        "phone": "+4915112345678",
        "address": {
          "line1": "Unter den Linden 1",
          "city": "Berlin",
          "stateOrRegion": "BE",
          "postalCode": "10117",
          "country": "DE"
        }
      },
      "bankName": null,
      "accountSuffix": "6789",
      "currency": "eur",
      "country": "DE",
      "entityType": "individual",
      "bic": "COBADEFFXXX"
    }
  }
  ```

  ```json US Bank Account theme={null}
  {
    "paymentMethodId": "f2ecef7e-91af-4fa7-93f9-12db856c227f",
    "default": false,
    "displayName": "Chime ••6259",
    "type": "bank-account-us",
    "bankAccount": {
      "billing": {
        "name": "Alice Smith",
        "phone": "+12125551234",
        "address": {
          "line1": "123 Main St",
          "city": "New York",
          "stateOrRegion": "NY",
          "postalCode": "10001",
          "country": "US"
        }
      },
      "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"
    }
  }
  ```

  ```json MX Bank Account theme={null}
  {
    "paymentMethodId": "27bacbe1-d0ff-4bc3-b37a-ca91cc64fa39",
    "default": false,
    "displayName": "MX Bank Account ••9719",
    "type": "bank-account-mx-clabe",
    "bankAccount": {
      "billing": {
        "name": "Javier Toledo",
        "phone": "+525512345678",
        "address": {
          "line1": "Av. Reforma 1",
          "city": "Mexico City",
          "stateOrRegion": "CDMX",
          "postalCode": "06600",
          "country": "MX"
        }
      },
      "bankName": null,
      "accountSuffix": "9719",
      "currency": "mxn",
      "country": "MX",
      "entityType": "individual",
      "bankCode": "138"
    }
  }
  ```

  ```json CO Bank Account theme={null}
  {
    "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
    "default": false,
    "displayName": "CO Bank Account ••7890",
    "type": "bank-account-co",
    "bankAccount": {
      "billing": {
        "name": "Carlos Gómez",
        "phone": "+573001234567",
        "address": {
          "line1": "Carrera 7",
          "city": "Bogotá",
          "stateOrRegion": "DC",
          "postalCode": "110010",
          "country": "CO"
        }
      },
      "bankName": null,
      "accountSuffix": "7890",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "bankCode": "001",
      "accountType": "savings"
    }
  }
  ```
</ResponseExample>


# Update a Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/update-payment-method

patch /unstable/payment-methods/{paymentMethodId}
Update the billing details or default status of an existing payment method

Updates a payment method's billing details or default status. Only `default` and `billingDetails` 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

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 [Staging](https://staging.crossmint.com/console) or [Production](https://www.crossmint.com/console) 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 login to see your NFT in the Crossmint wallet later, which can be accessed from [crossmint.com](https://crossmint.com) or [staging.crossmint.com](https://staging.crossmint.com) 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

put /2025-06-09/users/{userLocator}/identity-verification
Trigger identity verification for a user.

**API scope required**: `users.create`



# Upload a User Document
Source: https://docs.crossmint.com/api-reference/users/upload-document

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

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

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

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

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

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 />


# Retrieve credential nfts
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/retrieve-credential-nfts

get /api/v1-alpha1/wallets/{walletLocator}/credential_nfts

<Snippet />


# Revoke Credential
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/revoke-credential

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

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

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

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

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

get /v1-alpha1/credentials/types/{typeName}
Get the schema of a given type by name (or id)
        
**API scope required** `credentials.read`


<Snippet />


# Approve Signature
Source: https://docs.crossmint.com/api-reference/wallets/approve-signature

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

delete /2025-06-09/wallets/{walletLocator}/signers/{signer}
Remove an operational signer from a smart wallet.

**API scope required**: `wallets.create`



# Transfer Token
Source: https://docs.crossmint.com/api-reference/wallets/transfer-token

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 our 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. We **strongly recommend** 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="Add 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="Add login and logout functionality">
    <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="Add 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`.

## 1. Configure 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.

## 2. Custom Routes Implementation

### 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>

### 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>

## 3. Client Configuration

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.


# 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

Our 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 and the user's residency.

## Requirements for non-US residents

The following tables show what information is required for each activity type 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 |
| ------------------- | :-----: | :--------: |
| userDetails         |    ✅    |      ✅     |
| kycData             |         |      ✅     |
| dueDiligence        |         |      ✅     |
| verificationHistory |         |      ✅     |

### Document Requirements

Specific documents may be required depending on the activity. Use the [Upload Document API](/api-reference/users/upload-document) to upload the necessary materials.

| Document Type     | Payouts | On/offramp | On/offramp with EDD\* |
| ----------------- | :-----: | :--------: | :-------------------: |
| Identity document |         |      ✅     |           ✅           |
| Selfie            |         |      ✅     |           ✅           |
| Proof of address  |         |            |           ✅           |
| Proof of income   |         |            |           ✅           |

\*Enhanced Due Diligence (EDD) is required for high-risk individuals or regions.

<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

The same data and document requirements apply for users residing in the United States, with the following exceptions:

* The `kycData.phoneNumber` field is **required** for US residents (it is optional for non-US residents).
* The `dueDiligence` object is **not required** for US residents in most states. However, it is **required** for residents of the following states: **New York (NY)**, **North Carolina (NC)**, **Tennessee (TN)**, **Texas (TX)**, and **Virginia (VA)**.
* When you include the `dueDiligence` object for a US resident, its `estimatedYearlyIncome` field is **required** (it is optional for non-US residents). For standard offramp in states that do not require due diligence, you can omit the `dueDiligence` object entirely.
* US residents provide their identity via SSN in the `kycData.identityDocument` field (type `"ssn"`). No identity document upload or selfie is required for standard on/offramp. However, if Enhanced Due Diligence (EDD) is triggered, US users must also upload a passport (`id-passport`) or driver's license (`id-idcard-front`, `id-idcard-back`).
* Proof of income is **not required** for US residents under EDD.

## 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>


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

Register user data to enable access to regulated Crossmint products.

Crossmint's regulated products for stablecoin orchestration, including [onramp](/onramp/overview), offramp, and [payouts](/stablecoin-orchestration/regulated-transfers/overview)—require user data registration to comply with financial regulations. Compliance checks are performed by Crossmint when a registered user attempts a regulated action.

## How it works

* **Run initial verification**: Your company runs or identifies existing KYC, ID verification, and liveness checks with your own IDV provider (such as Persona or Sumsub)
* **Pass KYC data to Crossmint**: Share that KYC data with Crossmint via API so that regulated actions (onramp, offramp, payouts) can leverage that existing KYC data
* **Crossmint handles additional screening**: Crossmint runs sanction and PEP (Politically Exposed Persons) screens, and performs ongoing monitoring to ensure compliance

<Note> If your company has not provided all required information, users will be prompted to provide it client-side when initiating a regulated activity, as it's done with [Crossmint Onramp](/onramp/overview). </Note>

## Data Requirements Vary

The information required for each user depends on the country and the activity type:

* **Payouts**: Basic user details for payouts
* **Onramp/Offramp**: Additional user information

See the [Data Requirements](/identity/data-requirements) page for a detailed breakdown of required fields.

## Getting Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/identity/quickstart">
    Register your first user and upload documents in minutes.
  </Card>

  <Card title="Data Requirements" icon="table" href="/identity/data-requirements">
    See what data is required for each activity and region.
  </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>
</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

    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"] // "proof-of-address" and "proof-of-income" may also be requested in case of Enhanced Due Diligence 
            },
            {
                "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"] // "proof-of-address" and "proof-of-income" may also be requested in case of Enhanced Due Diligence 
            },
            {
                "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`, `proof-of-income`
    * 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. However, if Enhanced Due Diligence (EDD) is triggered, US users must also upload a passport (`id-passport`) or driver's license (`id-idcard-front`, `id-idcard-back`). Proof of income is **not** required for US EDD users.</Note>

    <Note>Calling this endpoint again with the same `userLocator` and `documentType` will update the existing document's registered information.</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>

## 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 server API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) 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: {
                    adminSigner: {
                        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: {
                    adminSigner: {
                        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>


# 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:

```
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

### Overview

Model Context Protocol (MCP) is a standard that enables AI agents to connect quickly and efficiently to external tools or data sources.

### Server Details

Instead of loading the entire documentation with every interaction, the server receives your query and returns only the most relevant sections.

* **Name:** Crossmint Docs
* **URL:** [https://docs.crossmint.com/mcp](https://docs.crossmint.com/mcp)
* **Transport:** Streamable HTTP

### Installation

<Tabs>
  <Tab title="Claude Code">
    Run the following command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http crossmint-docs https://docs.crossmint.com/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add it globally by opening the command palette (`Cmd/Ctrl + Shift + P`) and selecting `> Cursor Settings > Tools & MCP > Add Custom MCP`:

    ```json theme={null}
    {
        "mcpServers": {
            "Crossmint Docs": {
                "type": "http",
                "url": "https://docs.crossmint.com/mcp"
            }
        }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add it globally by opening the command palette (`Cmd/Ctrl + Shift + P`) and selecting `MCP: Open User Configuration`:

    ```json theme={null}
    {
        "servers": {
            "Crossmint Docs": {
                "type": "http",
                "url": "https://docs.crossmint.com/mcp"
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Usage

Once you have configured and connected the MCP Server, your agent will have access to a single tool called `SearchCrossmintDocs`. This tool allows it to search through the Crossmint documentation to find relevant information, code examples, API references, and guides.

**Example queries (input):**

* "How to create non-custodial wallets for my users"
* "How to get a staging API key"
* "Does Crossmint support Solana?"
* "How to implement transfer webhooks?"

**Example output:**

A list of results that includes the following fields: Title, Link, and Content, along with code examples when available.

```json theme={null}
{
    "results": [
        {
            "title": "Server Wallets Quickstart",
            "link": "https://docs.crossmint.com/solutions/story-protocol/wallets/server-side-wallets",
            "content": "In this quickstart, you will create new user wallets on Story...",
            "codeExample": "const response = await fetch('https://staging.crossmint.com/api/2022-06-09/wallets', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': '<YOUR_API_KEY>',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    type: '<WALLET_TYPE>',\n    linkedUser: 'email:user@example.com'\n  })\n});"
        },
        {
            "title": "Amazon Integration Steps",
            "link": "https://docs.crossmint.com/solutions/ai-agents/agentic-commerce/inventory",
            "content": "Create a project in the Crossmint Console...",
            "codeExample": "const crossmintOrder = await fetch(`https://${baseUrl}.crossmint.com/api/2022-06-09/orders`, {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': `${API_KEY}`,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    recipient: {\n      email: 'john@example.com'\n    },\n    lineItems: [{ productLocator: 'amazon:B00O79SKV6' }]\n  })\n});"
        }
    ]
}
```


# 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">
        Sell tokens and 1 billion physical products.
      </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 the recovery signer and can be scoped with specific permissions. Examples: a device key for user wallets, a server key 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 signer**                     | A signer used to regain access to a wallet when the operational signer is lost — for example, when a user gets a new phone. Recovery signers authorize the enrollment of a new operational signer without changing the wallet address. See [Signers](/wallets/concepts/signers).                                                                                                         |
| **Admin signer**                        | The previous term for **recovery signer**. You may still encounter this term in older SDK versions and 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 signers — 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-based money movement, including [onramps](/onramp/overview) and offramps, [payouts and transfers](/stablecoin-orchestration/regulated-transfers/overview), and [checkout flows](/payments/introduction). These APIs enable accepting, sending, converting, and settling value 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, payment flows, 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>


# 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'll 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'll 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, we recommend 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're 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'll 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'll 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, [contact us](https://www.crossmint.com/contact/sales).</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    | 50 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 our 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.


# 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 is a group of token collections, user wallets, API keys, billing information, and more.

    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">
    Projects can be shared across multiple team members. You can add new members from the Members tab on the console. All members get the same permissions, except for the ability to delete other members, which only belongs to the creator of the project.

    <Note>In order to invite a member to a project, they must already have a Crossmint account within that same environment.</Note>

    <Check>If you need to remove a team member, <a href="https://help.crossmint.com/hc/en-us/requests/new">submit a ticket with Crossmint support</a>.</Check>
  </Tab>
</Tabs>


# Staging vs Production Environments
Source: https://docs.crossmint.com/introduction/platform/staging-vs-production



Crossmint's console and first-party wallet operate in two different environments:

* **Staging:** free, for testing.
* **Production:** for your live projects. Blockchain operations incur credit costs.

You may access them from [https://staging.crossmint.com](https://staging.crossmint.com), and [https://www.crossmint.com](https://www.crossmint.com).

<Tip>Staging provides free self-serve access to most functionality.</Tip>

## Differences between the Environments

|              | **Staging**                                                    | **Production**                                         |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------ |
| URL          | [https://staging.crossmint.com](https://staging.crossmint.com) | [https://www.crossmint.com](https://www.crossmint.com) |
| Payments     | Test credit cards                                              | Accepts real credit cards                              |
| API Credits  | Free to test (no API credits required)                         | API credits required for some endpoints                |
| Verification | Checkout does not require KYC or collection verification       | Checkout requires KYC and collection verification      |
| Blockchains  | Testnets like Sepolia, and Amoy                                | Mainnets                                               |

## FAQ

<AccordionGroup>
  <Accordion title="Does staging activity appear in the production account, and viceversa?">
    No, collections created in one environment will not appear in the other.

    Typically, you would start developing your project in staging, and replicate and launch in production when you feel ready.
  </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 our 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. We will attempt 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, after these attempts, we're unable to deliver the message, we will mark it 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, payment processing, 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
* **Payment processing**: 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">
    We are going to use 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. We recommend 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

    We use 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:

    ```
    v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
    ```

    Make sure to remove the version prefix and delimiter (e.g. `v1,`) before verifying the signature.

    Please note that to compare the signatures it's recommended to use a constant-time string comparison method in order to prevent timing attacks.

    ### Verify timestamp

    We include 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 |    Mainnet Label   |        Testnet Label       |
| :---------------- | :-----: | :------: | :----: | :----------: | :----------------: | :------------------------: |
| Apex              |    -    |     ✅    |    ✅   |       -      |       `apex`       |              -             |
| Abstract          |    ✱    |     ✅    |    ✱   |       ✱      |     `abstract`     |     `abstract-testnet`     |
| Atleta            |    ✱    |     ✅    |    ✅   |       ✅      |      `atleta`      |      `atleta-testnet`      |
| ApeChain          |    ✅    |     ✅    |    ✅   |       ✅      |     `apechain`     |          `curtis`          |
| Arc               |    ✅    |     ✱    |    ✱   |       ✱      |        `arc`       |        `arc-testnet`       |
| Aptos             |    ✱    |     ✱    |    ✱   |       ✅      |       `aptos`      |           `aptos`          |
| Arbitrum One      |    ✅    |     ✅    |    ✅   |       ✅      |     `arbitrum`     |     `arbitrum-sepolia`     |
| Arbitrum Nova     |    ✅    |     ✅    |    ✅   |       ✅      |   `arbitrumnova`   |     `arbitrum-sepolia`     |
| Astar             |    ✱    |     ✅    |    ✅   |       ✅      |    `astar-zkevm`   |          `zkyoto`          |
| Avalanche         |    ✱    |     ✅    |    ✅   |       ✅      |     `avalanche`    |      `avalanche-fuji`      |
| Avalanche Subnets |    ✱    |     ✱    |    ✱   |       ✱      | `avalanche-subnet` | `avalanche-subnet-testnet` |
| Base              |    ✅    |     ✅    |    ✅   |       ✅      |       `base`       |       `base-sepolia`       |
| BSC               |    ✅    |     ✱    |    ✱   |       ✱      |        `bsc`       |        `bsc-testnet`       |
| Chiliz            |    ✱    |     ✅    |    ✅   |       ✅      |      `chiliz`      |   `chiliz-spicy-testnet`   |
| Coti              |    ✱    |     ✅    |    ✅   |       ✅      |       `coti`       |       `coti-testnet`       |
| Ethereum          |    ✱    |     ✅    |    ✅   |       ✱      |     `ethereum`     |     `ethereum-sepolia`     |
| Flow              |    ✱    |     ✅    |    ✱   |       ✅      |       `flow`       |       `flow-testnet`       |
| Hedera EVM        |    ✱    |     ✅    |    ✅   |       ✅      |      `hedera`      |      `hedera-testnet`      |
| Mantle            |    ✅    |     ✅    |    ✅   |       ✅      |      `mantle`      |      `mantle-testnet`      |
| Mode              |    ✅    |     ✅    |    ✅   |       ✅      |       `mode`       |       `mode-sepolia`       |
| Monad             |    ✱    |     ✱    |    ✱   |       ✱      |       `monad`      |       `monad-testnet`      |
| Optimism          |    ✅    |     ✅    |    ✅   |       ✅      |     `optimism`     |     `optimism-sepolia`     |
| Polygon           |    ✅    |     ✅    |    ✅   |       ✅      |      `polygon`     |       `polygon-amoy`       |
| Rari              |    ✱    |     ✅    |    ✅   |       ✅      |       `rari`       |       `rari-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`   |
| Soneium           |    ✱    |     ✅    |    ✅   |       ✅      |      `soneium`     |  `soneium-minato-testnet`  |
| Story             |    ✅    |     ✱    |    ✱   |       ✅      |   `story-mainnet`  |       `story-testnet`      |
| Sui               |    ✱    |     ✱    |    ✱   |       ✅      |        `sui`       |              -             |
| Tempo             |    ✅    |     ✱    |    ✱   |       ✱      |       `tempo`      |       `tempo-testnet`      |
| U2U               |    ✱    |     ✅    |    ✅   |       ✅      |    `u2u-solaris`   |        `u2u-nebulas`       |
| Xion              |    ✱    |     ✅    |    ✅   |       ✅      |       `xion`       |       `xion-testnet`       |
| Xai               |    ✱    |     ✅    |    ✅   |       ✅      |        `xai`       |    `xai-sepolia-testnet`   |
| Zenchain          |    ✱    |     ✅    |    ✅   |       ✅      |     `zenchain`     |     `zenchain-testnet`     |
| Zora              |    ✅    |     ✅    |    ✅   |       ✅      |       `zora`       |       `zora-sepolia`       |
| Other EVM chains  |    ✱    |     ✱    |    ✱   |       ✱      |                    |                            |

**Legend:**

* `✅` Supported
* `✱` Available, but not self-serve. [Contact us](https://www.crossmint.com/contact/sales) to request it for your project.
* `-` Not supported

Notes:

* Fungible token checkout available self service only in Solana. [Contact us](https://www.crossmint.com/contact/sales) for other chains.

<Card title="Building on a different chain?" icon="comment" href="https://www.crossmint.com/contact/sales">
  Contact us. We launch new chains regularly and yours is likely in the pipeline.
</Card>

## Testnets

You can access testnets by using the [staging console](https://staging.crossmint.com/console). 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.


# 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 |
| Mode            |            \$0.05 |            \$0.05 |       \$0.05 |         \$0.05 |          \$0.05 |
| 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 |
| Rari            |            \$0.20 |            \$0.20 |       \$0.20 |         \$0.20 |          \$0.20 |
| 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 |
| Viction         |            \$0.01 |            \$0.01 |       \$0.01 |         \$0.01 |          \$0.01 |
| Xai             |            \$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.


# 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 selects the fastest available rail for the destination. See [Payment Schemes](/offramp/payment-methods) for rail-specific 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.                                                             |
| **Enhanced Due Diligence (EDD)** | High-risk individuals or regions                                                     | Full KYC data plus proof of address and proof of income                                                                                                                                                                    |

<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>

## 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>


# Collect Bank Accounts
Source: https://docs.crossmint.com/offramp/guides/collect-bank-accounts

Save and manage your users' bank accounts as reusable payment methods

Before a user can cash out, you [save their bank account](/api-reference/headless/payment-methods/create-payment-method) as a **payment method**. Saved payment methods are reusable across Crossmint products, so a user enters their details once.

## Save a bank account

The request body depends on the payment method `type`. See [The Payment Method Object](/api-reference/headless/payment-methods/payment-method-object) for the full list of types and fields.

<Note>The examples below use the staging URL, `https://vault.staging.crossmint.com`. In production, use `https://vault.crossmint.com`. See [Launch in Production](/offramp/guides/going-to-production) for all the differences between environments.</Note>

<Tabs>
  <Tab title="US">
    ```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": "userId:<USER_ID>",
        "bankAccount": {
          "accountNumber": "6349881141",
          "routingNumber": "026009593",
          "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"
            }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Europe">
    ```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-sepa-iban",
        "userLocator": "userId:<USER_ID>",
        "bankAccount": {
          "iban": "DE89370400440532013000",
          "bic": "COBADEFFXXX",
          "currency": "eur",
          "country": "DE",
          "entityType": "individual",
          "billing": {
            "name": "Hans Müller",
            "phone": "+4915112345678",
            "address": {
              "line1": "Unter den Linden 1",
              "city": "Berlin",
              "stateOrRegion": "BE",
              "postalCode": "10117",
              "country": "DE"
            }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Mexico">
    ```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-mx-clabe",
        "userLocator": "userId:<USER_ID>",
        "bankAccount": {
          "accountNumber": "138180000123459719",
          "currency": "mxn",
          "country": "MX",
          "entityType": "individual",
          "billing": {
            "name": "Javier Toledo",
            "phone": "+525512345678",
            "address": {
              "line1": "Av. Reforma 1",
              "city": "Mexico City",
              "stateOrRegion": "CDMX",
              "postalCode": "06600",
              "country": "MX"
            }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Colombia">
    ```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-co",
        "userLocator": "userId:<USER_ID>",
        "bankAccount": {
          "accountNumber": "123456787890",
          "bankCode": "001",
          "accountType": "savings",
          "documentType": "CC",
          "documentNumber": "1234567890",
          "currency": "cop",
          "country": "CO",
          "entityType": "individual",
          "billing": {
            "name": "Carlos Gómez",
            "phone": "+573001234567",
            "address": {
              "line1": "Carrera 7",
              "city": "Bogotá",
              "stateOrRegion": "DC",
              "postalCode": "110010",
              "country": "CO"
            }
          }
        }
      }'
    ```
  </Tab>
</Tabs>

The response returns the saved payment method, including its `paymentMethodId`, the resolved `bankName`, and a masked `accountSuffix` (banks use `accountSuffix`, not `last4`). Pass the `paymentMethodId` as the `recipient` when you [create an order](/offramp/quickstarts/rest-api).

<Accordion title="Example response">
  ```json theme={null}
  {
    "paymentMethodId": "d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc",
    "default": false,
    "displayName": "Chase ••1141",
    "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": "1141",
      "currency": "usd",
      "country": "US",
      "entityType": "individual",
      "bankAddress": {
        "line1": "420 Montgomery St",
        "city": "San Francisco",
        "stateOrRegion": "CA",
        "postalCode": "94104",
        "country": "US"
      },
      "routingNumber": "026009593",
      "accountType": "checking"
    }
  }
  ```
</Accordion>

<Note>Saving an account does not require the user to be verified yet, but creating an order does. Before you offramp with this account, 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 bank account types, see [The Payment Method Object](/api-reference/headless/payment-methods/payment-method-object) in the API reference.

## List, update, and remove

Reads and non-sensitive updates go through the standard API. Use it to [list a user's payment methods](/api-reference/headless/payment-methods/list-payment-methods), [fetch one](/api-reference/headless/payment-methods/get-payment-method), [update billing details](/api-reference/headless/payment-methods/update-payment-method), or [remove an account](/api-reference/headless/payment-methods/delete-payment-method).

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Use a saved account in an offramp
  </Card>

  <Card title="KYC & Compliance" icon="id-card" href="/offramp/concepts/kyc-and-compliance">
    Verification requirements
  </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)) or for Enhanced Due Diligence, which adds document checks.
    </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.

    ```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="Collect Bank Accounts" 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>


# 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](/api-reference/headless/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

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,44} 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"
        }
      },
      "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": {
    "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" } }]
    }
    ```
  </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                                                                                                                             |
    | :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
    | `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                                                                 |
    | :----------------- | :---------------------------------------------------------------------- |
    | `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`, `slippage-tolerance-exceeded`, `payment-refunded`.

    <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](/api-reference/headless/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                        |
</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">
    If the user does not send the stablecoin deposit before the quote expires, the order returns to the `quote` phase. No funds are collected.

    ```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.
  </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": "transfer-failed" }
          }
        }
      ]
    }
    ```

    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>


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

<video />

<Note>**Offramping from a corporate treasury wallet?** See the [Treasury offramps guide](/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets).</Note>

## 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">
    Collect Bank Accounts
  </Card>

  <Card title="Track order status" icon="list-check" href="/offramp/guides/manage-orders">
    Track order status
  </Card>
</CardGroup>


# Payment Schemes
Source: https://docs.crossmint.com/offramp/payment-methods

Supported payout rails and geographies for Crossmint Offramp

Crossmint Offramp supports multiple payout rails across geographies. The table below lists the available schemes by currency.

| Rail/Scheme                             | Availability                                                        | Settlement           | Cut-off Time (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)                  | July                                                                | Seconds              | 24/7                        | €500,000 per transaction       |
| **SEPA** (EUR)                          | July                                                                | 1 to 2 business days | GMT 07:00am to 02:00pm      | No limit                       |
| **SWIFT** (EUR)                         | July                                                                | 1 to 5 business days | GMT 07:00am to 02:00pm      | No limit                       |
| **T2** (EUR)                            | Q3                                                                  | Same day             |                             |                                |
| **Faster Payments** (GBP)               | B2B: July/August, Consumer: Q3/Q4                                   | Minutes to hours     | 24/7                        | £1,000,000 per transaction     |
| **SPEI** (MXN)                          | July/August                                                         | Minutes              |                             |                                |
| **Bre-B** (COP)                         | July/August                                                         | Instant              |                             | COP 12,110,000 per transaction |
| **Bank Transfer** (COP)                 | July/August                                                         | 1 to 2 business days |                             |                                |
| **Pix** (BRL)                           | July/August                                                         | Instant              |                             |                                |
| Additional rails available upon request | <a href="https://www.crossmint.com/contact/sales">Contact sales</a> |                      |                             |                                |

<Accordion title="Cut-off times by timezone">
  Settlements arrive within the stated timeframes only if payments are submitted by the stipulated cut-off time (COT).

  ### 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 |
</Accordion>


# 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/api-reference/headless/payment-methods/create-payment-method">Create Payment Method</a> API reference for the full request schema and supported payment method types.

    ```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": "6349881141",
          "routingNumber": "026009593",
          "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",
        "default": false,
        "displayName": "Chase ••1141",
        "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": "1141",
          "currency": "usd",
          "country": "US",
          "entityType": "individual",
          "bankAddress": {
            "line1": "420 Montgomery St",
            "city": "San Francisco",
            "stateOrRegion": "CA",
            "postalCode": "94104",
            "country": "US"
          },
          "routingNumber": "026009593",
          "accountType": "checking"
        }
      }
      ```
    </Accordion>

    For listing, updating, and removing saved accounts, see [Collect Bank Accounts](/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
          recovery: { type: "server", secret: process.env.CROSSMINT_SIGNER_SECRET }, // server admin signer
          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.
        * **`recovery`** sets a `server` signer 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`.

    <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": {
            "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.

    <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.
      </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",
              "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>
</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>


# 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>


# 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 KYC data](/identity/register-user-data) with Crossmint
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

## Accept Crossmint's Privacy Policy

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>. Record their acceptance with the [Accept Legal Document](/api-reference/users/accept-legal-document) endpoint **before** registering KYC data:

```bash cURL theme={null}
curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:YOUR_USER_ID/legal-documents' \
    --header 'X-API-KEY: <x-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "crossmint-privacy-policy",
        "acceptedAt": "2025-10-05T14:48:00Z"
    }'
```

See the [Identity Quickstart](/identity/quickstart) for more details on the privacy policy and the users endpoints.

## 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 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>

### Linking KYC Data to Orders

When you create an order, Crossmint automatically looks up the user's KYC data based on the email address provided in `payment.receiptEmail`. Here is the complete flow:

<Steps>
  <Step title="Accept the privacy policy">
    Record the user's privacy-policy acceptance first (see the **Accept Crossmint's Privacy Policy** section above). This is required before any KYC data is shared with Crossmint.
  </Step>

  <Step title="Register user with KYC data">
    First, register the user's KYC information using the [Create User API](/api-reference/users/upsert-user). Make sure to include the user's email in the `email` field within `kycData`:

    ```javascript theme={null}
    const userLocator = "userId:YOUR_USER_ID";

    const options = {
        method: 'PUT',
        headers: {
            'X-API-KEY': 'YOUR_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: "YOUR_USER_EMAIL",
                identityDocument: {
                    type: "passport",
                    number: "AS12321",
                    issuingCountryCode: "DE"
                },
                ipAddresses: ["203.0.113.1"]
            }
        })
    };

    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>

  <Step title="Create order with matching email">
    When creating the onramp order, use the same email address in `payment.receiptEmail`:

    ```javascript 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));
    ```
  </Step>
</Steps>

## 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="Registering a User" icon="user-plus" href="/identity/register-user-data" />

  <Card title="Data Requirements" icon="list-check" href="/identity/data-requirements" />
</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>

<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` follows the [CAIP-122](https://chainagnostic.org/CAIPs/caip-122) standard.
  </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>

    The user must sign the `preparation.message` returned in the order response using their wallet's private key.

    <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>


# 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">
    ```jsx 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">
    ```jsx 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="iOS (Swift)">
    Apple Pay is supported automatically in native iOS apps via the Swift SDK — no domain verification is required. 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">
        ```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="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. **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>


# Proof of Ownership
Source: https://docs.crossmint.com/onramp/guides/proof-of-ownership

Understand when and how wallet ownership verification works for onramp transactions

When onramping to non-Crossmint wallets, the onramp may require the user to prove they own the recipient wallet by signing a message. This is a legal requirement under anti-money laundering (AML) and counter-terrorism financing (CTF) regulations, which mandate verification of the beneficiary wallet owner's identity above certain transaction thresholds. This page explains when proof of ownership is required and how it works.

## When Is Proof of Ownership Required?

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>
  Proof of ownership only applies to **external (non-Crossmint) wallets**. A Crossmint-managed wallet does not require ownership verification **as long as it was created with its `owner` set to the user**. A Crossmint wallet created without an `owner` (or owned by someone else) is treated as external and must be linked and verified like any other external wallet.
</Note>

<Note>
  Wallet-ownership proof applies only to users verified outside the United States. Buyers whose KYC country of residence is the United States are not asked to prove wallet ownership, regardless of transaction amount.
</Note>

## How It Works

<Steps>
  <Step title="Link External Wallet">
    Before creating an onramp order to an external wallet, link the wallet to a Crossmint user (created automatically if one does not yet exist for the locator) using the Link External Wallet API:

    ```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"
        }'
    ```

    The API responds with a verification challenge following the <a href="https://chainagnostic.org/CAIPs/caip-122">CAIP-122</a> standard:

    ```json theme={null}
    {
        "address": "0x1234...5678",
        "chain": "base-sepolia",
        "type": "external-wallet",
        "ownership": {
            "verified": false,
            "verificationChallenge": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\n..."
        }
    }
    ```
  </Step>

  <Step title="Create Order">
    Create the onramp order as usual. If verification is required, the order response will have status `requires-recipient-verification`:

    ```json theme={null}
    {
        "order": {
            "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="Sign the Message">
    Have the user sign the `preparation.message` using their wallet's private key:

    <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 YOUR_SECRET_KEY_BYTES = new Uint8Array(64); // Replace with your actual secret key bytes
      const keypair = nacl.sign.keyPair.fromSecretKey(YOUR_SECRET_KEY_BYTES);

      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">
    Submit the signature as proof of ownership using the same Link External Wallet API:

    ```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 verified, the response confirms ownership:

    ```json theme={null}
    {
        "address": "0x1234...5678",
        "chain": "base-sepolia",
        "type": "external-wallet",
        "ownership": {
            "verified": true
        }
    }
    ```
  </Step>

  <Step title="Complete Order">
    After ownership is verified, fetch the order using the [Get Order API](/api-reference/headless/get-order). The status will advance to:

    * **`requires-kyc`** — the user has not completed KYC yet.
    * **`awaiting-payment`** — the user can proceed to payment.
  </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. This avoids requiring verification during the checkout flow.

```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"
    }'
```

## Related Resources

* [Onramp to Non-Crossmint Wallets](/onramp/guides/onramp-to-external-wallets) — full guide for non-Crossmint wallet onramp integration
* [React Quickstart (External Wallets tab)](/onramp/quickstarts/react) — quickstart with external wallet support


# 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",
            },
        },
    }}
/>
```

## 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)


# Restricted Countries
Source: https://docs.crossmint.com/onramp/introduction/restricted-countries

Regions where the onramp is not available

The following countries are **not supported** for onramp transactions:

| Region       | Restricted Countries                                                                                                                                                     |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Africa**   | Burundi, Central African Republic, Democratic Republic of the Congo, Djibouti, Guinea, Guinea-Bissau, Libya, Mali, Niger, Somalia, South Sudan, Sudan, Tunisia, Zimbabwe |
| **Asia**     | Afghanistan, Iran, Iraq, Lebanon, Myanmar, North Korea, Palestine, Syria, Yemen                                                                                          |
| **Europe**   | Belarus, Bosnia and Herzegovina, Moldova, Montenegro, Russia, Serbia, Ukraine                                                                                            |
| **Americas** | Bolivia, Cuba, Guatemala, Haiti, Nicaragua, Venezuela                                                                                                                    |

<Warning>
  This list may be updated based on regulatory changes.
</Warning>

## How Restrictions Work

* **IP-based blocking** — users connecting from restricted regions will not be able to initiate onramp transactions.
* **KYC-based blocking** — users whose identity documents indicate residence in a restricted country will be blocked during the KYC verification process.
* **Sanctions screening** — users found on international sanctions lists, including OFAC, EU, and UN lists, will be blocked from completing onramp transactions.

## Questions

If you have questions about availability in a specific country or region, <a href="https://www.crossmint.com/contact/sales">contact Crossmint</a>.


# 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 three 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.                                        |
| **Enhanced Due Diligence (EDD)** | High-risk individuals or regions                                                     | Full KYC data plus proof of address and proof of income                                                                                                                                               |

### 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.
      </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 Enhanced Due Diligence (EDD) is required, the component handles that 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.
      </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 Full KYC or EDD 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.
      </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="Proof of Wallet Ownership" icon="fingerprint" href="/onramp/guides/proof-of-ownership" />
</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, Crossmint handles payment processing, compliance, and chargebacks, so your team can focus on building great products.

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 handle payment processing 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>

## 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

Select your framework to begin integrating. 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 Nat." 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>

## Learn More

* [User Onboarding](/onramp/introduction/user-onboarding)
* [Data Requirements](/identity/data-requirements)
* [Restricted Countries](/onramp/introduction/restricted-countries)

## 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>

  <Card title="Proof of Ownership" icon="fingerprint" href="/onramp/guides/proof-of-ownership">
    Verify external wallets
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="How can I test the product? And how do I move to production?">
    Staging is fully self-serve — 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 **\$1,000 per user and day**. 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

## Requirements

* Flutter 3.x+
* Dart SDK ^3.11.4
* iOS 13.0+ / Android 5.0+

## 1. Prerequisites

<Steps>
  <Step title="Install the SDK">
    <Snippet />

    You also need the `http` package for making API requests to your backend:

    ```bash theme={null}
    flutter pub add http
    ```
  </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.

    <br />

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

  <Step title="Add environment variables">
    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>
  </Step>
</Steps>

## 2. 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);
```

## 3. Build an 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();
  }
}
```

## 4. 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>

## 5. Transaction Completion

<Snippet />

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

## Requirements

* **Android SDK 24+**
* **Jetpack Compose**
* Android Studio Arctic Fox or later

## 1. Installation

Install the Crossmint Kotlin SDK using Maven Central.

<Steps>
  <Step title="Add Dependency">
    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")
    }
    ```
  </Step>

  <Step title="Create API key">
    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.
  </Step>
</Steps>

## 2. Create 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 />

## 3. Use 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

## 4. Track Order

<Snippet />

## 5. Transaction Completion

<Snippet />

## 6. 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>

## 1. Prerequisites

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

    <Snippet />
  </Step>

  <Step title="Create API keys">
    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.
  </Step>

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

    ```sh .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>

<Tabs>
  <Tab title="Onramp to Crossmint Wallets">
    ## 2. 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();
    }
    ```

    ## 3. 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>
        );
    }
    ```

    ## 4. 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's 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.
  </Tab>

  <Tab title="Onramp to External Wallets">
    Use this tab if you want to onramp to external wallets — 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.

    ## 2. Link 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` (following the <a href="https://chainagnostic.org/CAIPs/caip-122">CAIP-122</a> standard) that you can use later to verify ownership.
    * If you pass it, you prove ownership of the wallet in the same request.

    ## 3. 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..."
            }
        }
    }
    ```

    ## 4. Handle Wallet Verification

    If the order requires ownership verification, the user must sign the `preparation.message` returned in the order response using their wallet's private key.

    <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`).

    ## 5. 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>
        );
    }
    ```

    ## 6. 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.
  </Tab>
</Tabs>

<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>

## Requirements

* React Native 0.60+
* Expo (recommended) or bare React Native CLI
* iOS 13.0+ / Android 5.0+

## 1. Prerequisites

<Steps>
  <Step title="Install the SDK">
    <Snippet />
  </Step>

  <Step title="Create API keys">
    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.
  </Step>

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

    ```sh .env 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>
  </Step>
</Steps>

## 2. 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);
```

## 3. Build an 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",
    },
});
```

## 4. 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's 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>

## 5. Transaction Completion

<Snippet />

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

## Requirements

* **iOS 14.0+**
* **SwiftUI** framework
* Xcode 13.0 or later

## 1. Installation

Install the Crossmint Swift SDK using Swift Package Manager.

<Steps>
  <Step title="Add Package Dependency">
    In Xcode, go to **File > Add Package Dependencies** and add:

    ```
    https://github.com/Crossmint/crossmint-checkout-swift
    ```

    Select the `CrossmintCheckout` product for your target.
  </Step>

  <Step title="Create API key">
    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.
  </Step>
</Steps>

## 2. Create 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 />

## 3. Use 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

## 4. Track Order

<Snippet />

## 5. Transaction Completion

<Snippet />

## 6. 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, Hyperspace, 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": "stripe-payment-element"  // 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

2. **No Code Storefront**
   * Mint to specific template is not currently supported on No Code Storefront. If you'd like this feature, please reach out to your CSE rep

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 "thirdweb-drop" 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: "stripe-payment-element",
                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>

    <Accordion title="Using a thirdweb contract?">
      Add a claim phase with currency type `USDC`. In staging. you must use `Custom ERC-20` and specify one of the token address listed above. In mainnet, you should select the default USDC option.
    </Accordion>
  </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 payment processing, 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

<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}
    {
        "type": "orders.quote.created",
        "payload": {
            "totalPrice": {
                "amount": "0.50",
                "currency": "usd"
            },
            "lineItems": [
                {
                    "metadata": {
                        "title": "Collection Name",
                        "description": "Collection Description",
                        "imageUrl": "https://..."
                    },
                    "price": {
                        "amount": "0.50",
                        "currency": "usd"
                    },
                    "quantity": 1
                }
            ]
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.payment.succeeded">
    ```json theme={null}
    {
        "type": "orders.payment.succeeded",
        "payload": {
            "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
            "paymentMethodType": "credit-card",
            "totalPrice": {
                "amount": "0.50",
                "currency": "usd"
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.delivery.completed">
    ```json theme={null}
    {
        "type": "orders.delivery.completed",
        "payload": {
            "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
            "lineItems": [
                {
                    "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",
                                "quantity": "1500000",
                                "symbol": "TOKEN",
                                "decimals": 6
                            }
                        ]
                    }
                }
            ]
        }
    }
    ```

    <Note>
      The `quantity`, `symbol`, and `decimals` fields are optional and only present when applicable (e.g., for fungible token purchases in exact-in execution mode).
    </Note>
  </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>


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

***

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)


# 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                                                   |

### 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>
  ```

  ```tsx productLocator theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintEmbeddedCheckout
          lineItems={{
              productLocator: "amazon:B01DFKC2SO", // Amazon ASIN
              // productLocator: "amazon:https://www.amazon.com/dp/B01DFKC2SO", // Amazon URL
              // productLocator: "shopify:https://your-store.myshopify.com/products/product-name:123456789", // Shopify
          }}
      />
  </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, wallet address, or physical address for physical products.

### 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>
```

### Physical Product Recipients

<Snippet />

When purchasing physical products, you can specify a physical address for delivery:

```jsx React {5-13} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintEmbeddedCheckout
        recipient={{
            email: "user@example.com",
            physicalAddress: {
                name: "John Doe",
                line1: "123 Main St",
                line2: "Apt 4B", // optional
                city: "San Francisco",
                state: "CA",
                postalCode: "94105",
                country: "US",
            },
        }}
        // 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",
            },
        },
    }}
/>
```

## 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

* [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)


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

## 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>


# 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>

## 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 and Storefront. 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
    * **Hyperspace**: Cross-chain NFT marketplace and aggregator

    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 and Storefront. 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, Hyperspace

<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"`, `"thirdweb-drop"`
    * **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" }.
  ```

  ```json productLocator theme={null}
  {
    "lineItems": [
      {
        "productLocator": "amazon:B01DFKC2SO", // Amazon ASIN
        // "productLocator": "amazon:https://www.amazon.com/dp/B01DFKC2SO", // Amazon URL
        // "productLocator": "shopify:https://your-store.myshopify.com/products/product-name:123456789", // Shopify
      }
    ]
  }
  ```
</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 productLocator 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",
              physicalAddress: {
                  name: "John Doe",
                  line1: "123 Main St",
                  city: "San Francisco",
                  state: "CA",
                  postalCode: "94105",
                  country: "US",
              },
          },
          payment: {
              method: "ethereum-sepolia",
              currency: "eth",
          },
          lineItems: [
              {
                  productLocator: "amazon:B01DFKC2SO", // Amazon ASIN
                  // productLocator: "amazon:https://www.amazon.com/dp/B01DFKC2SO", // Amazon URL
                  // productLocator: "shopify:https://your-store.myshopify.com/products/product-name:123456789", // Shopify
              }
          ],
      }),
  };

  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>

<Note>
  For more details on physical product purchases, see our guides for [Amazon
  Integration](/payments/headless/guides/providers/amazon) and [Shopify
  Integration](/payments/headless/guides/providers/shopify).
</Note>

<Snippet />


# Localization
Source: https://docs.crossmint.com/payments/headless/guides/localization

Customize the language of receipts and currency of the checkout

## Currencies and Languages Available

| 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.                                                                                                                                 |
| `payment.currency` | `usd` `aud` `eur` `gbp` `hkd` `inr` `jpy` `krw` `sgd` `vnd`                                                                       | Currency for the payment quote. The original price of the collection will be automatically converted to the selected currency using the most recent bank exchange rates. |

<Note>
  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.
</Note>

To customize the language use the property `locale` and for currency, set `currency` under the payment object. Here's an example:

```json {2,6} theme={null}
{
    "locale": "es-ES", // Price for receipt (e.g. Spanish customers)
    "payment": {
        "receiptEmail": "jsmith@example.com",
        "method": "card",
        "currency": "eur" // If collection is priced in USD, price returned for quote will be in EUR
    },
    "lineItems": [
        {
            "collectionLocator": "crossmint:76ced33d-fec8-4741-a69f-450f1ae09fa6",
            "callData": {
                "totalPrice": "<string>"
            }
        }
    ]
}
```

<Note>
  When implementing a headless checkout, you'll need to handle the display of localized content in your own UI based
  on the locale you've 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 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` any of the [supported fiat currencies](/payments/headless/guides/localization#currencies-and-languages-available).

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).


# Physical Product Purchases
Source: https://docs.crossmint.com/payments/headless/guides/physical-good-purchases

How to purchase physical products with crypto using Headless Checkout

Crossmint's Headless Checkout now supports purchasing physical products using a wallet's crypto balance through the `productLocator` parameter. This guide explains how to integrate physical product purchases and handle shipping requirements.

## Physical Address Requirement

When purchasing physical products, a shipping address is required (currently only US addresses are supported). You can provide this in two ways:

### 1. Include Address During Order Creation

```json theme={null}
POST /api/2022-06-09/orders
{
    "recipient": {
        "email": "buyer@example.com",
        "physicalAddress": {
            "name": "John Doe", // required
            "line1": "123 Main St", // required
            "line2": "Apt 4B", // optional
            "city": "San Francisco", // required
            "state": "CA", // required for US addresses
            "postalCode": "94105", // required
            "country": "US" // required - only US is currently supported
        }
    }
}
```

### 2. Update Address After Order Creation

If you create an order without specifying a `physicalAddress`, the quote cannot proceed until a valid shipping address is provided. See the full list of statuses on the <a href="/payments/headless/guides/status-codes">Status Codes</a> page.

To resolve this, update the order with the physical address:

```json theme={null}
PATCH /api/2022-06-09/orders/{orderId}
{
  "recipient": {
    "physicalAddress": {
      "name": "John Doe",      // required
      "line1": "123 Main St",  // required
      "line2": "Apt 4B",       // optional
      "city": "San Francisco", // required
      "state": "CA",           // required for US addresses
      "postalCode": "94105",   // required
      "country": "US"          // required - only US is currently supported
    }
  }
}
```

After providing the physical address, the order status will update and include the necessary `payment.preparation` parameters to proceed with payment.

## Order Status Handling

When purchasing physical products, provide a shipping address up front or update the order after creation. Until a valid address is present, the order cannot proceed to payment preparation. For the complete, authoritative list of statuses and their meanings, see the <a href="/payments/headless/guides/status-codes">Status Codes</a> page.

## Supported Providers

### Amazon

Amazon products can be purchased using either their ASIN or product URL. See the [Amazon Integration Guide](/payments/headless/guides/providers/amazon) for details.

### Shopify

Shopify products can be purchased using the product URL and variant ID. See the [Shopify Integration Guide](/payments/headless/guides/providers/shopify) for details.


# Order Errors
Source: https://docs.crossmint.com/payments/headless/guides/physical-product-order-errors

Common reasons why physical product orders may fail and how to resolve them

When purchasing physical products through Crossmint, your order may fail for various reasons. This guide explains the most common restrictions and requirements for different providers.

## Amazon

Amazon orders through Crossmint have specific requirements that must be met for successful processing. If your Amazon order fails, it may be due to one of the following restrictions:

### 1. Item must be sold by Amazon or a verified third-party seller

Only products sold directly by Amazon or through verified third-party sellers on the Amazon marketplace are supported. Items from unverified sellers or those with questionable seller ratings may be rejected.

### 2. Item must have standard shipping options available

The product must support standard shipping methods. Items that require special shipping arrangements, expedited delivery only, or have shipping restrictions may not be available for purchase.

### 3. Item must be a physical product (not digital goods or services)

Only physical products that can be shipped are supported. The following types of items are **not supported**:

* Digital downloads (software, music, ebooks)
* Digital gift cards
* Services or subscriptions
* Virtual products

### 4. Item must not be from specialty Amazon programs

Products from the following Amazon specialty programs are **not supported**:

* **Amazon Fresh** - Fresh grocery delivery service
* **Amazon Pantry** - Bulk household items program
* **Amazon Pharmacy** - Prescription medications and health products
* **Subscribe & Save** - Subscription-only items that require recurring delivery

## Need Help?

If you continue to experience issues after checking these requirements, please [contact support](https://portal.usepylon.com/crossmint/forms/contact-support) with:

* The specific product URL or identifier you're trying to purchase
* The complete error message you received
* Your shipping address details (city, state, country)

This information will help us quickly identify and resolve the issue with your order.


# 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>


# Amazon Integration
Source: https://docs.crossmint.com/payments/headless/guides/providers/amazon

How to enable crypto purchases of Amazon products using Headless Checkout

This guide explains how to integrate Amazon product purchases using the Headless Checkout API.

## Product Locator Format

When creating an order for an Amazon product, use the `productLocator` parameter with either the Amazon ASIN or product URL:

```json theme={null}
// Amazon ASIN
{
    "lineItems": [
        {
            "productLocator": "amazon:B01DFKC2SO"
        }
    ]
}

// Amazon Product URL
{
    "lineItems": [
        {
            "productLocator": "amazon:https://www.amazon.com/dp/B01DFKC2SO"
        }
    ]
}
```

## Example Flow

<Steps>
  <Step title="Create the order">
    * Specify the receipient's email
    * Specify their shipping information
    * Specify the payment method used
    * Specify the product locator

    <Check>
      For a full list of supported currencies, refer to the [supported
      currencies](/payments/headless/guides/supported-currencies) page.
    </Check>

    ```json theme={null}
    POST /api/2022-06-09/orders
    {
      "recipient": {
        "email": "buyer@example.com",
        "physicalAddress": {
          "name": "John Doe",      // required
          "line1": "123 Main St",  // required
          "city": "San Francisco", // required
          "state": "CA",           // required for US addresses
          "postalCode": "94105",   // required
          "country": "US"          // required - only US is currently supported
        }
      },
      "payment": {
        "method": "ethereum-sepolia",
        "currency": "eth"
      },
      "lineItems": [
        {
          "productLocator": "amazon:B01DFKC2SO"
        }
      ]
    }
    ```
  </Step>

  <Step title="Check order status">
    With all requied information provided, the order's response will include payment preparation details, as shown below.

    ```json theme={null}
    {
        "order": {
            "orderId": "...",
            "quote": {
                "status": "valid",
                ...
            },
            "payment": {
                "preparation": {
                    ...  // Payment details will be present here
                }
            }
        }
    }
    ```
  </Step>
</Steps>

## Additional Information

* Monitor order statuses through the [Developer Console](https://www.crossmint.com/console)
* Review the [Order Lifecycle guide](/payments/headless/guides/order-lifecycle/quote-phase) for detailed status handling
* Check [this guide](/payments/headless/guides/payment-methods) for details on supported currencies and payment methods


# Shopify Integration
Source: https://docs.crossmint.com/payments/headless/guides/providers/shopify

How to enable crypto purchases of Shopify products using Headless Checkout

This guide explains how to integrate Shopify product purchases using the Headless Checkout API.

## Product Locator Format

When creating an order for a Shopify product, use the `productLocator` parameter with the Shopify product URL and variant ID:

```json theme={null}
{
    "lineItems": [
        {
            "productLocator": "shopify:https://www.gymshark.com/products/gymshark-arrival-5-shorts-black-ss22:39786362601674"
        }
    ]
}
```

The format for the product locator is `shopify:<product-url>:<variant-id>`, where:

* `shopify:` is the prefix identifying this as a Shopify product
* `<product-url>` is the full URL to the product page
* `<variant-id>` is the unique variant ID for the specific product option (size, color, etc.)

## Example Flow

<Steps>
  <Step title="Create the order">
    * Specify the recipient's email
    * Specify their shipping information
    * Specify the payment method used
    * Specify the product locator

    <Check>
      For a full list of supported currencies, refer to the [supported
      currencies](/payments/headless/guides/supported-currencies) page.
    </Check>

    ```json theme={null}
    POST /api/2022-06-09/orders
    {
      "recipient": {
        "email": "buyer@example.com",
        "physicalAddress": {
          "name": "John Doe",      // required
          "line1": "123 Main St",  // required
          "city": "San Francisco", // required
          "state": "CA",           // required for US addresses
          "postalCode": "94105",   // required
          "country": "US"          // required - only US is currently supported
        }
      },
      "payment": {
        "method": "ethereum-sepolia",
        "currency": "eth"
      },
      "lineItems": [
        {
          "productLocator": "shopify:https://www.gymshark.com/products/gymshark-arrival-5-shorts-black-ss22:39786362601674"
        }
      ]
    }
    ```
  </Step>

  <Step title="Check order status">
    With all required information provided, the order's response will include payment preparation details, as shown below.

    ```json theme={null}
    {
        "order": {
            "orderId": "...",
            "quote": {
                "status": "valid",
                ...
            },
            "payment": {
                "preparation": {
                    ...  // Payment details will be present here
                }
            }
        }
    }
    ```
  </Step>
</Steps>

## Additional Information

* Monitor order statuses through the [Developer Console](https://www.crossmint.com/console)
* Review the [Order Lifecycle guide](/payments/headless/guides/order-lifecycle/quote-phase) for detailed status handling
* Check [this guide](/payments/headless/guides/payment-methods) for details on supported currencies and payment methods
* **Note:** Delivery destinations are limited to regions supported by the Shopify store itself. The ability to ship to a specific address depends on the merchant's shipping configuration.


# 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>

### Physical Product Recipients

<Snippet />

When purchasing physical products, providing a physical address is required. If you don't provide it in the initial order, you can update the order it later:

<Tabs>
  <Tab title="Create Order">
    ```json {5-13, 20} theme={null}
    POST /api/2022-06-09/orders
    {
      "recipient": {
        "email": "buyer@example.com", // Email address of the recipient
        "physicalAddress": {
          "name": "John Doe",
          "line1": "123 Main St",
          "line2": "Apt 4B", // optional
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      },
      "locale": "en-US",
      "payment": {
        "method": "ethereum-sepolia",
        "currency": "eth",
        "payerAddress": "0x1234abcd...",
        "receiptEmail": "buyer@example.com" // Optional — recommended for physical products
      },
      "lineItems": [
        {
          "collectionLocator": "crossmint:cosdahdasda",
          "callData": {
            "totalPrice": "0.0001",
            "quantity": 1
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Edit Order">
    ```json {4-12} theme={null}
    PATCH /api/2022-06-09/orders/{orderId}
    {
      "recipient": {
        "physicalAddress": {
          "name": "John Doe",
          "line1": "123 Main St",
          "line2": "Apt 4B", // optional
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  If you create an order with a physical product without specifying a `physicalAddress`, the quote cannot proceed
  until a physical address is provided. After providing the physical address, the order status will update and include
  the necessary `payment.preparation` parameters to proceed with payment. See the full list of statuses on the
  <a href="/payments/headless/guides/status-codes">Status Codes</a> page and learn more about payment preparation in the
  <a href="/payments/headless/guides/order-lifecycle/crypto-payment-phase">payment phase documentation</a>.
</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

* `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` — Payment processing is underway
* `completed` — Payment completed; the order proceeds to delivery/completion

## Delivery statuses

* `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.

## 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 payment flow 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 or processing 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, requires no KYC from buyers, includes built-in chargeback protection, and has market-leading approval rates. Sellers complete KYB once during onboarding to enable 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="No buyer KYC" icon="passport">
    No ID checks during onboarding.
  </Card>

  <Card title="95-98% Approval Rate" icon="greater-than">
    Compared to 55% industry benchmark.
  </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">
    Buy or sell via API, ideal 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.

    The checkout has no KYC, is available on any region non-sanctioned by OFAC, and offers the best UX and conversion rate. The onramp requires KYC and some geographical limitations apply.
  </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 integrations with payment processors, different states, and errors.
  </Accordion>

  <Accordion title="Which memecoins can be supported?">
    Our team continuously monitors market activity and proactively whitelists eligible memecoins across all of our partners. As of the last update, the Checkout supported memecoins representing around \~80% of the memecoin trading volume in the previous 24 hours.

    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 does settlement of payments and assets work?">
    Crossmint settles payments instantly with sellers directly via the smart contract, in the native currency specified
    on the contract. Assets are sent directly into the wallet of the buyer, without intermediation by Crossmint.
  </Accordion>

  <Accordion title="What happens if a buyer charges back their credit card?">
    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="Who pays for gas fees?">
    ### With Crossmint's contracts

    Managed Collections have two options for fees:

    **1. Buyer pays fees** - The buyer (your customer) pays the price of the asset you set in console, plus applicable fees. The Seller (you, the creator) receives the price set in console (aka *the payout*).

    **2. Seller pays fees** - The buyer pays the exact price of the asset set in console. You receive the set asset price, minus applicable fees.

    To access this setting in the Crossmint Console, go to your managed collection, click on "Payments" and then "Settings".
    Here you will find the "Who pays the fees?" switch, which allows you to set the payer of fees for your collection. You can update and save this setting at any time.

    * The total fees per transaction are the same in either option.
    * Managed collections are Buyer pays by default.

    ### With imported contracts

    Imported collections are only compatible with the "Buyer pays fees" option.
  </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="Does Crossmint support primaries and secondaries (marketplaces)?">
    Crossmint supports primary and secondary sales for closed-loop tokens and [NFTs](/payments/advanced/marketplaces-and-launchpads). For memecoins, Crossmint only supports secondary sales.
  </Accordion>

  <Accordion title="What's the pricing model?">
    For more information, <a href="https://www.crossmint.com/contact/sales">contact sales</a>.
  </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>
</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>
  ```

  ```tsx productLocator theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintHostedCheckout
          lineItems={{
              productLocator: "amazon:B01DFKC2SO", // Amazon ASIN
              // productLocator: "amazon:https://www.amazon.com/dp/B01DFKC2SO", // Amazon URL
              // productLocator: "shopify:https://your-store.myshopify.com/products/product-name:123456789", // Shopify
          }}
      />
  </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, wallet address, or physical address for physical products.

### 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>
```

### Physical Product Recipients

<Snippet />

When purchasing physical products, you can specify a physical address for delivery:

```jsx React {3-13} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintHostedCheckout
        recipient={{
            email: "user@example.com",
            physicalAddress: {
                name: "John Doe",
                line1: "123 Main St",
                line2: "Apt 4B", // optional
                city: "San Francisco",
                state: "CA",
                postalCode: "94105",
                country: "US",
            },
        }}
        projectId="YOUR_PROJECT_ID"
        collectionId="YOUR_COLLECTION_ID"
        environment="staging"
        mintConfig={{
            totalPrice: "0.0001",
            quantity: 1,
        }}
    />
</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>


# 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,
})
```

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.

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

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


# 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
```


# 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>

***

## 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)
```


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

### 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']}');
  },
)
```


# 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?`    | -           |


# 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, 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)           |
| 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)
```

## Constructors

```kotlin theme={null}
constructor(rules: CheckoutAppearanceRules? = null)
```

## Properties

| Property | Type                       | Description |
| -------- | -------------------------- | ----------- |
| `rules`  | `CheckoutAppearanceRules?` | -           |


# 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 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, label: CheckoutLabelRule? = null, input: CheckoutInputRule? = null, tab: CheckoutTabRule? = null, primaryButton: CheckoutPrimaryButtonRule? = null)
```

## Properties

| Property            | Type                             | Description |
| ------------------- | -------------------------------- | ----------- |
| `destinationInput`  | `CheckoutDestinationInputRule?`  | -           |
| `input`             | `CheckoutInputRule?`             | -           |
| `label`             | `CheckoutLabelRule?`             | -           |
| `primaryButton`     | `CheckoutPrimaryButtonRule?`     | -           |
| `receiptEmailInput` | `CheckoutReceiptEmailInputRule?` | -           |
| `tab`               | `CheckoutTabRule?`               | -           |


# 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 text: String? = null, val background: String? = null, val border: String? = null, val boxShadow: String? = null, val placeholder: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(text: String? = null, background: String? = null, border: String? = null, boxShadow: String? = null, placeholder: String? = null)
```

## Properties

| Property      | Type      | Description |
| ------------- | --------- | ----------- |
| `background`  | `String?` | -           |
| `border`      | `String?` | -           |
| `boxShadow`   | `String?` | -           |
| `placeholder` | `String?` | -           |
| `text`        | `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`                 | -           |


# 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 size: String? = null, val weight: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(family: String? = null, size: String? = null, weight: String? = null)
```

## Properties

| Property | Type      | Description |
| -------- | --------- | ----------- |
| `family` | `String?` | -           |
| `size`   | `String?` | -           |
| `weight` | `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 borderRadius: String? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val focus: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, focus: CheckoutStateStyle? = null)
```

## Properties

| Property       | Type                  | Description |
| -------------- | --------------------- | ----------- |
| `borderRadius` | `String?`             | -           |
| `colors`       | `CheckoutColorStyle?` | -           |
| `focus`        | `CheckoutStateStyle?` | -           |
| `font`         | `CheckoutFontStyle?`  | -           |
| `hover`        | `CheckoutStateStyle?` | -           |


# 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 borderRadius: String? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val disabled: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, disabled: CheckoutStateStyle? = null)
```

## Properties

| Property       | Type                  | Description |
| -------------- | --------------------- | ----------- |
| `borderRadius` | `String?`             | -           |
| `colors`       | `CheckoutColorStyle?` | -           |
| `disabled`     | `CheckoutStateStyle?` | -           |
| `font`         | `CheckoutFontStyle?`  | -           |
| `hover`        | `CheckoutStateStyle?` | -           |


# 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 borderRadius: String? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val selected: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, selected: CheckoutStateStyle? = null)
```

## Properties

| Property       | Type                  | Description |
| -------------- | --------------------- | ----------- |
| `borderRadius` | `String?`             | -           |
| `colors`       | `CheckoutColorStyle?` | -           |
| `font`         | `CheckoutFontStyle?`  | -           |
| `hover`        | `CheckoutStateStyle?` | -           |
| `selected`     | `CheckoutStateStyle?` | -           |


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


# 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

* [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)

## 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)
* [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)
* [CheckoutFontStyle](/sdk-reference/checkout/kotlin/data-classes/checkout-font-style)
* [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)

## 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)


# 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="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" />

        <ResponseField name="spacingUnit" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clientSecret" type="string" />

<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.


# 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>
    );
}
```


# 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="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" />

        <ResponseField name="spacingUnit" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clientSecret" type="string" />

<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

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


# 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>
    );
}
```


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


# 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,
})
```

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,
})
```

### 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`        | Resets isOTPRequired to emit 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()
```

Resets isOTPRequired to emit 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, otp: String): Result<String, TEEError>
```


# 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`     | -           |
| `reset`       | -           |
| `sendMessage` | -           |

### getWebView

```kotlin theme={null}
fun getWebView(): WebView?
```

### loadUrl

```kotlin theme={null}
open suspend override fun loadUrl(url: String, timeout: Duration)
```

### reset

```kotlin theme={null}
open override fun reset()
```

### 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

**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 in-flight OTP signing request.                                |
| `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 in-flight OTP signing request.

### 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 |
| `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                                                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                                                   |
| `listTransfers`      | Lists transfers for this wallet.                                                                                                                                     |
| `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.                                            |
| `removeSigner`       | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator. |
| `send`               | Sends tokens to a recipient address.                                                                                                                                 |
| `sendTransaction`    | Submits a raw transaction and polls until it reaches a terminal state.                                                                                               |
| `signerIsRegistered` | Returns true if the given locator is registered as a delegated signer 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.                                                                                                                           |
| `useSigner`          | Sets the active signer for subsequent send and approve operations.                                                                                                   |
| `withSigner`         | Creates a new Wallet instance that uses the specified signer for transactions.                                                                                       |

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner): 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.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### 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(): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator.

### 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(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer 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.

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


# 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`     | -           |
| `reset`       | -           |
| `sendMessage` | -           |

### loadUrl

```kotlin theme={null}
open suspend override fun loadUrl(url: String, timeout: Duration)
```

### reset

```kotlin theme={null}
open override fun reset()
```

### 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.                                                                                                                                                        |
| `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.

### 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 |
| `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                                                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                                                   |
| `listTransfers`      | Lists transfers for this wallet.                                                                                                                                     |
| `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.                                            |
| `removeSigner`       | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator. |
| `send`               | Sends tokens to a recipient address.                                                                                                                                 |
| `sendTransaction`    | Submits a raw transaction and polls until it reaches a terminal state.                                                                                               |
| `signerIsRegistered` | Returns true if the given locator is registered as a delegated signer on this wallet.                                                                                |
| `signers`            | Fetches the live list of signers registered on this wallet.                                                                                                          |
| `useSigner`          | Sets the active signer for subsequent send and approve operations.                                                                                                   |
| `withSigner`         | Creates a new Wallet instance that uses the specified signer for transactions.                                                                                       |

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner): 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.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### 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(): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator.

### 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(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

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


# 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 |
| `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                                                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                                                   |
| `listTransfers`      | Lists transfers for this wallet.                                                                                                                                     |
| `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.                                            |
| `removeSigner`       | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator. |
| `send`               | Sends tokens to a recipient address.                                                                                                                                 |
| `sendTransaction`    | Submits a raw transaction and polls until it reaches a terminal state.                                                                                               |
| `signerIsRegistered` | Returns true if the given locator is registered as a delegated signer on this wallet.                                                                                |
| `signers`            | Fetches the live list of signers registered on this wallet.                                                                                                          |
| `useSigner`          | Sets the active signer for subsequent send and approve operations.                                                                                                   |
| `withSigner`         | Creates a new Wallet instance that uses the specified signer for transactions.                                                                                       |

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner): 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.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### 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(): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator.

### 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(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

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


# 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 |
| `owner`     | `Owner?`       | The owner of the wallet, if available           |
| `type`      | `WalletType`   | The type of wallet (smart wallet or MPC wallet) |

## Functions

| Function             | Description                                                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                                                   |
| `listTransfers`      | Lists transfers for this wallet.                                                                                                                                     |
| `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.                                            |
| `removeSigner`       | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator. |
| `send`               | Sends tokens to a recipient address.                                                                                                                                 |
| `sendTransaction`    | Submits a raw transaction and polls until it reaches a terminal state.                                                                                               |
| `signerIsRegistered` | Returns true if the given locator is registered as a delegated signer on this wallet.                                                                                |
| `signers`            | Fetches the live list of signers registered on this wallet.                                                                                                          |
| `useSigner`          | Sets the active signer for subsequent send and approve operations.                                                                                                   |
| `withSigner`         | Creates a new Wallet instance that uses the specified signer for transactions.                                                                                       |

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner): 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.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### 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(): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator.

### 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(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

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


# 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?`    | -           |


# 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)
```

## Constructors

```kotlin theme={null}
constructor(locator: String, status: DelegatedSignerStatus = DelegatedSignerStatus.UNKNOWN)
```

## 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`                | -                                                                                                                                                               |
| `status`     | `DelegatedSignerStatus` | -                                                                                                                                                               |
| `type`       | `DelegatedSignerType`   | The signer type derived from the locator prefix (e.g. "device:", "email:"). Returns DelegatedSignerType.UNKNOWN for prefix-less locators (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, 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. |


# 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) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(phoneNumber: 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. |
| `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` | -           |


# 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` | -           |


# 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`  | Base64url-encoded authenticator data from the assertion response. |
| `challengeIndex`           | `Int`     | Byte offset of `"challenge"` in clientDataJSON (default 23).      |
| `clientDataJSON`           | `String`  | Base64url-encoded client data JSON from the assertion response.   |
| `typeIndex`                | `Int`     | Byte offset of `"type"` in clientDataJSON (default 1).            |
| `userVerificationRequired` | `Boolean` | Whether user verification is required (default true).             |


# 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 authenticator metadata required by on-chain P256 verifier contracts.         |
| `r`        | `String`              | The r component of the ECDSA P-256 signature, 0x-prefixed hex, low-s normalized. |
| `s`        | `String`              | The s component of the ECDSA P-256 signature, 0x-prefixed hex, low-s normalized. |


# 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` | -           |


# 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`             | -                                                   |


# 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` | -           |


# 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` | -           |


# 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) : SignerSelection
```

## Constructors

```kotlin theme={null}
constructor(delegatedSigner: DelegatedSignerData)
```

## Properties

| Property          | Type                  | Description |
| ----------------- | --------------------- | ----------- |
| `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.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) : SignerType
```

## Constructors

```kotlin theme={null}
constructor(phoneNumber: String)
```

## Properties

| Property      | Type     | Description |
| ------------- | -------- | ----------- |
| `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`     | -           |


# TEEError.SignerStatusRegression
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/tee-error-signer-status-regression

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SignerStatusRegression(val message: String) : TEEError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property  | Type         | Description |
| --------- | ------------ | ----------- |
| `cause`   | `Throwable?` | -           |
| `message` | `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)
```

## Constructors

```kotlin theme={null}
constructor(symbol: String, name: String, decimals: Int, amount: String, rawAmount: String, chainInfo: ChainInfo? = null)
```

## Properties

| Property    | Type         | Description |
| ----------- | ------------ | ----------- |
| `amount`    | `String`     | -           |
| `chainInfo` | `ChainInfo?` | -           |
| `decimals`  | `Int`        | -           |
| `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` | -           |
| `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`               | -                                                   |


# 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())
```

## Constructors

```kotlin theme={null}
constructor(adminSigner: SignerData, delegatedSigners: List<DelegatedSignerData> = emptyList())
```

## Properties

| Property           | Type                        | Description |
| ------------------ | --------------------------- | ----------- |
| `adminSigner`      | `SignerData`                | -           |
| `delegatedSigners` | `List<DelegatedSignerData>` | -           |


# 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.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.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.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.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.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.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.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) : 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`          | -                                                   |


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


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


# 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`                 | -           |

## 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`        | -           |

## 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`               | -           |

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


# Kotlin SDK Reference
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/index

API reference for the Crossmint Kotlin SDK

# Kotlin SDK Reference

## Classes

* [AndroidCrossmintTEE](/sdk-reference/wallets/kotlin/classes/android-crossmint-tee)
* [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)
* [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)
* [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)
* [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)
* [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)
* [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.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)
* [TEEError.SignerStatusRegression](/sdk-reference/wallets/kotlin/data-classes/tee-error-signer-status-regression)
* [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)
* [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.DeviceSignerNotSupported](/sdk-reference/wallets/kotlin/data-classes/wallet-error-device-signer-not-supported)
* [WalletError.Forbidden](/sdk-reference/wallets/kotlin/data-classes/wallet-error-forbidden)
* [WalletError.InvalidInput](/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-input)
* [WalletError.InvalidSigner](/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-signer)
* [WalletError.RateLimited](/sdk-reference/wallets/kotlin/data-classes/wallet-error-rate-limited)
* [WalletError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/wallet-error-service-not-initialized)
* [WalletError.SignerNotRegistered](/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-not-registered)
* [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)
* [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)
* [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)
* [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)
* [LogLevel](/sdk-reference/wallets/kotlin/enums/log-level)
* [NetworkErrorCode](/sdk-reference/wallets/kotlin/enums/network-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

* [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)
* [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)


# 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`        | Resets isOTPRequired to emit 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()
```

Resets isOTPRequired to emit 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): 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.                                                                |
| `createWallet`                 | Creates a new wallet on the specified chain with the given signer.                                                                                                                       |
| `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`                    | Fetches the wallet for 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.                                                           |

### addSigner

```kotlin theme={null}
abstract suspend fun addSigner(signer: DelegatedSigner, chain: Chain): Result<Unit, WalletError>
```

Adds a delegated signer to the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator.

### createWallet

```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 new wallet on the specified chain with the given signer.

```kotlin theme={null}
abstract suspend fun createWallet(chain: EVMChain, recovery: SignerType, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<EVMWallet, WalletError>
```

Creates a new EVM wallet on the specified chain with the given signer.

```kotlin theme={null}
abstract suspend fun createWallet(chain: SolanaChain, recovery: SignerType, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<SolanaWallet, WalletError>
```

Creates a new Solana wallet with the given signer.

```kotlin theme={null}
abstract suspend fun createWallet(chain: StellarChain, recovery: SignerType, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<StellarWallet, WalletError>
```

Creates a new Stellar wallet with the given signer.

### 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>
```

Fetches the wallet for the current user on the given chain.

```kotlin theme={null}
abstract suspend fun getWallet(chain: EVMChain): Result<EVMWallet, WalletError>
```

Fetches the EVM wallet for the current user on the given chain.

```kotlin theme={null}
abstract suspend fun getWallet(chain: SolanaChain): Result<SolanaWallet, WalletError>
```

Fetches the Solana wallet for the current user.

```kotlin theme={null}
abstract suspend fun getWallet(chain: StellarChain): Result<StellarWallet, WalletError>
```

Fetches the Stellar wallet for the current user.

### removeSigner

```kotlin theme={null}
abstract suspend fun removeSigner(signer: DelegatedSigner, chain: Chain): Result<Unit, WalletError>
```

Removes a delegated signer from the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator.


# 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.                                                                                                                                                        |
| `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.

### 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` | -           |


# 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
```

## Functions

| Function             | Description                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addSigner`          | Registers a new delegated signer on the wallet via the recovery/approval flow. Does not change the active signer.                                                   |
| `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.                                           |
| `removeSigner`       | Removes a delegated signer from the wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator. |
| `signerIsRegistered` | Returns true if the given locator is registered as a delegated signer on this wallet.                                                                               |
| `signers`            | Fetches the live list of signers registered on this wallet from the API.                                                                                            |
| `useSigner`          | Sets the active signer for subsequent wallet operations.                                                                                                            |

### addSigner

```kotlin theme={null}
abstract suspend fun addSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Registers a new delegated signer on the wallet via the recovery/approval flow. Does not change the active signer.

### 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(): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeSigner

```kotlin theme={null}
abstract suspend fun removeSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Removes a delegated signer from the wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator.

### signerIsRegistered

```kotlin theme={null}
abstract fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer 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.

### useSigner

```kotlin theme={null}
abstract suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent wallet operations.


# 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`           | -                                    |
| `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>
```

### 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>
```


# 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?`    | -           |


# 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).


# 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`     | -           |


# 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 : 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).


# 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`           | -                                                   |


# 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 : 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).


# 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 : 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).


# 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react-native/get-started) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

### 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react-native/hooks) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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">
      The recovery signer configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </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="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="signer" 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="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="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.addSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#addsigner)                   | Add a signer to the wallet. Always uses the recovery signer internally to approve the registration. 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.removeSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#removesigner)             | Remove a signer from the wallet. Always uses the recovery signer internally to approve the removal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`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.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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react-native/providers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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">
      The recovery signer configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react/get-started) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

### 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react/hooks) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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">
      The recovery signer configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </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="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="signer" 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="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="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.addSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#addsigner)                   | Add a signer to the wallet. Always uses the recovery signer internally to approve the registration. 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.removeSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#removesigner)             | Remove a signer from the wallet. Always uses the recovery signer internally to approve the removal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`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.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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/react/providers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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">
      The recovery signer configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </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 `Signer.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**

```swift theme={null}
actor CrossmintAuthManager
```

## 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:)

```swift theme={null}
func confirmEmailOtp(email: String, code: String) async throws(AuthManagerError) -> OTPAuthenticationStatus
```

### logout()

```swift theme={null}
func logout() async throws(AuthManagerError) -> OTPAuthenticationStatus
```

### oneTimeSecretAuthentication(oneTimeSecret:)

```swift theme={null}
func oneTimeSecretAuthentication(oneTimeSecret: String) async throws(AuthManagerError) -> OTPAuthenticationStatus
```

### reset()

```swift theme={null}
func reset() async -> OTPAuthenticationStatus
```

### sendEmailOtp(email:)

```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
```

Call `configure(apiKey:logLevel:)` once at app startup before accessing `shared`. Accessing `shared` before configuring causes a `fatalError`.
When using an email OTP signer, observe `isOTPRequired` to know when to display an OTP input, then call `submit(otp:)` with the code the user enters.

```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 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
```

> **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)
```

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**

```swift theme={null}
actor DefaultAuthClient
```

## 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:)

```swift theme={null}
init(service: any SmartWalletService, secureWalletStorage: any SecureWalletStorage)
```

## 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
```

### 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

### addSigner(\_:chainType:chainName:)

Inherited from `WalletService.addSigner(_:chainType:chainName:)`.

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String) 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]
```

### getWallet(\_:)

Inherited from `WalletService.getWallet(_:)`.

```swift theme={null}
func getWallet(_ request: GetMeWalletRequest) async throws(WalletError) -> WalletApiModel
```

### listTransfers(\_:)

Inherited from `TransferService.listTransfers(_:)`.

```swift theme={null}
func listTransfers(_ params: ListTransfersQueryParams) async throws(WalletError) -> TransferListResult
```

### registerTypedSigner(\_:chainType:chainName:)

Inherited from `WalletService.registerTypedSigner(_:chainType:chainName:)`.

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String) async throws(WalletError) -> AddDelegatedSignerResponse
```

### 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
```

### 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`          | -                                    |
| `isInitialized` | `Bool`            | -                                    |
| `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 `Signer.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**

```swift theme={null}
class EVMWallet
```

## Instance Methods

### 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:)

```swift theme={null}
func sendTransaction(to address: String, value: String?, data: String?, chain: EVMChain? = nil) async throws(TransactionError) -> TransactionSummary
```

### signMessage(\_:signer:isSmartWalletSignature:)

```swift theme={null}
func signMessage(_ message: String, signer: (any AdminSignerData)? = nil, isSmartWalletSignature: Bool = true) async throws(SignatureError) -> String
```

### signTypedData(\_:signer:isSmartWalletSignature:)

```swift theme={null}
func signTypedData(_ typedData: EIP712.TypedData, signer: (any AdminSignerData)? = nil, isSmartWalletSignature: Bool = true) async throws(SignatureError) -> String
```

## Type Aliases

### EVMWallet.SpecificChain

Inherited from `WalletOnChain.SpecificChain`.

```swift theme={null}
typealias SpecificChain = EVMChain
```

## Type Methods

### from(wallet:)

```swift theme={null}
static func from(wallet: Wallet) throws(WalletError) -> EVMWallet
```


# 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 `Signer.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
```


# 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`          | -                                    |
| `isInitialized` | `Bool`            | -                                    |
| `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**

```swift theme={null}
final class SolanaWallet
```

## Instance Methods

### sendTransaction(transaction:)

```swift theme={null}
func sendTransaction(transaction: String) async throws(TransactionError) -> TransactionSummary
```

### 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`          | -                                    |
| `isInitialized` | `Bool`            | -                                    |
| `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` | -           |

## Instance Methods

### addSigner(\_:)

```swift theme={null}
func addSigner(_ config: SignerConfig) async throws(WalletError)
```

### approve(transactionId:)

```swift theme={null}
func approve(transactionId id: String) async throws(TransactionError) -> Transaction
```

### balance(of:)

```swift theme={null}
func balance(of tokens: [CryptoCurrency] = []) async throws(WalletError) -> Balances
```

### balances(\_:\_:)

```swift theme={null}
func balances(_ tokens: [CryptoCurrency] = [], _ chains: [Chain] = []) async throws(WalletError) -> Balance
```

### fund(token:amount:)

```swift theme={null}
func fund(token: CryptoCurrency, amount: Int) async throws(WalletError)
```

### listTransfers(tokens:)

```swift theme={null}
func listTransfers(tokens: [CryptoCurrency]) async throws(WalletError) -> TransferListResult
```

### needsRecovery()

```swift theme={null}
func needsRecovery() async -> Bool
```

### nfts(page:nftsPerPage:)

```swift theme={null}
func nfts(page: Int, nftsPerPage: Int) async throws(WalletError) -> [NFT]
```

### recover()

```swift theme={null}
func recover() async throws(WalletError)
```

### removeSigner(locator:)

```swift theme={null}
func removeSigner(locator: String) async throws(TransactionError) -> Transaction
```

### send(\_:\_:\_:idempotencyKey:)

```swift theme={null}
func send(_ walletLocator: String, _ tokenLocator: String, _ amount: Double, idempotencyKey: String? = nil) async throws(TransactionError) -> TransactionSummary
```

### send(token:recipient:amount:)

```swift theme={null}
func send(token: CryptoCurrency, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction
```

### signerIsRegistered(\_:)

```swift theme={null}
func signerIsRegistered(_ locator: String) async -> Bool
```

### signers()

```swift theme={null}
func signers() async throws(WalletError) -> [WalletDelegatedSignerConfigApiModel]
```

### transferToken(tokenId:recipient:amount:)

```swift theme={null}
func transferToken(tokenId: String? = nil, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction
```

### useSigner(\_:)

```swift theme={null}
func useSigner(_ config: SignerConfig) async throws(WalletError)
```


# 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**

```swift theme={null}
enum AuthenticationStatus
```

## Enumeration Cases

| Case                               | Description |
| ---------------------------------- | ----------- |
| `authenticated(email:jwt:secret:)` | -           |
| `authenticating`                   | -           |
| `nonAuthenticated`                 | -           |

## Instance Properties

| Property          | Type   | Description |
| ----------------- | ------ | ----------- |
| `isAuthenticated` | `Bool` | -           |


# AuthError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/autherror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum AuthError
```

## Enumeration Cases

| Case               | Description |
| ------------------ | ----------- |
| `generic(_:)`      | -           |
| `serviceError(_:)` | -           |
| `signInRequired`   | -           |

## 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`     | -           |
| `invalidInput(_:)` | -           |
| `noPendingOTP`     | -           |
| `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
```


# EmailSignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/emailsignererror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum EmailSignerError
```

## Enumeration Cases

| Case            | Description |
| --------------- | ----------- |
| `generic(_:)`   | -           |
| `nonAvailable`  | -           |
| `teeNotStarted` | -           |


# 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:)` | -           |

## 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`. |


# OTPAuthenticationStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/otpauthenticationstatus

Swift Enumeration

**Enumeration**

```swift theme={null}
enum OTPAuthenticationStatus
```

## Enumeration Cases

| Case                        | Description |
| --------------------------- | ----------- |
| `authenticationStatus(_:)`  | -           |
| `emailSent(email:emailId:)` | -           |

## Instance Properties

| Property          | Type      | Description |
| ----------------- | --------- | ----------- |
| `email`           | `String?` | -           |
| `isAuthenticated` | `Bool`    | -           |


# 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(_:)` | -           |
| `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**

```swift theme={null}
enum SignerConfig
```

## Enumeration Cases

| Case                  | Description |
| --------------------- | ----------- |
| `apiKey`              | -           |
| `device`              | -           |
| `email(_:)`           | -           |
| `externalWallet(_:)`  | -           |
| `passkey(name:host:)` | -           |
| `phone(_:)`           | -           |


# 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`         | -           |
| `invalidAddress`    | -           |
| `invalidEmail`      | -           |
| `invalidMessage`    | -           |
| `invalidPrivateKey` | -           |
| `invalidSigner`     | -           |
| `notStarted`        | -           |
| `passkey(_:)`       | -           |
| `signingFailed`     | -           |

## Enumerations

### SignerError.PasskeyError

```swift theme={null}
enum PasskeyError
```


# 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` | -           |


# 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`        | -           |

## 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**

```swift theme={null}
enum SolanaSigners
```

## Enumeration Cases

| Case        | Description |
| ----------- | ----------- |
| `apiKey`    | -           |
| `email(_:)` | -           |

## 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(_:)` | -           |

## 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?
```


# 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**

```swift theme={null}
enum TransactionStatus
```

## Enumeration Cases

| Case               | Description |
| ------------------ | ----------- |
| `awaitingApproval` | -           |
| `failed`           | -           |
| `pending`          | -           |
| `success`          | -           |

## 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**

```swift theme={null}
enum TransferType
```

## Enumeration Cases

| Case       | Description |
| ---------- | ----------- |
| `incoming` | -           |
| `outgoing` | -           |

## 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
```


# UnknownMapping
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/unknownmapping

Swift Enumeration

**Enumeration**

```swift theme={null}
enum UnknownMapping
```

## Type Aliases

### UnknownMapping.APIModel

Inherited from `WalletTypeTransactionMapping.APIModel`.

```swift theme={null}
typealias APIModel = UnknownApiTransaction
```

## Type Properties

| Property    | Type        | Description                                              |
| ----------- | ----------- | -------------------------------------------------------- |
| `chainType` | `ChainType` | Inherited from `WalletTypeTransactionMapping.chainType`. |


# 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(_:)` | -           |
| `invalidChain(chain:)`         | -           |
| `invalidToken(token:)`         | -           |
| `serviceError(_:)`             | -           |
| `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`.    |


# 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
```


# AuthClient
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/authclient

Swift Protocol

**Protocol**

```swift theme={null}
protocol AuthClient : Sendable
```

## Instance Methods

### logout()

```swift theme={null}
func logout() async
```

### sendOTP(to:)

```swift theme={null}
func sendOTP(to email: String) async throws(AuthError) -> OTPRequest
```

### verifyOTP(code:requestId:)

```swift theme={null}
func verifyOTP(code: String, requestId: String) async throws(AuthError) -> AuthSession
```


# AuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/authmanager

Swift Protocol

**Protocol**

```swift theme={null}
protocol AuthManager : Sendable
```

## Instance Properties

| Property | Type      | Description |
| -------- | --------- | ----------- |
| `jwt`    | `String?` | -           |

## Instance Methods

### setJWT(\_:)

```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**

```swift theme={null}
protocol ChainWithSigners : SpecificChain
```

## 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**

```swift theme={null}
protocol CrossmintWallets : Sendable
```

## Instance Methods

### createWallet(chain:recovery:options:)

```swift theme={null}
func createWallet(chain: Chain, recovery: any Signer, options: WalletOptions?) async throws(WalletError) -> Wallet
```

### getWallet(chain:recovery:options:)

```swift theme={null}
func getWallet(chain: Chain, recovery: any Signer, options: WalletOptions?) async throws(WalletError) -> Wallet?
```


# 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> : Sendable
```

## 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]
```

### initialize()

```swift theme={null}
func initialize() async throws(SignerError)
```

### initialize(\_:)

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```

### 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(withService:)

```swift theme={null}
func toDomain(withService service: any SmartWalletService) -> 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
```

### 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

### addSigner(\_:chainType:chainName:)

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String) 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)
```

### getWallet(\_:)

```swift theme={null}
func getWallet(_ request: GetMeWalletRequest) async throws(WalletError) -> WalletApiModel
```

### registerTypedSigner(\_:chainType:chainName:)

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String) async throws(WalletError) -> AddDelegatedSignerResponse
```

### removeSigner(\_:chainType:chainName:)

```swift theme={null}
func removeSigner(_ signerLocator: String, chainType: ChainType, chainName: String) 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)
```


# AccountWalletConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/accountwalletconfig

Swift Structure

**Structure**

```swift theme={null}
struct AccountWalletConfig
```

## Structures

### AccountWalletConfig.Signer

```swift theme={null}
struct Signer
```


# 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?`             | -                                           |
| `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**

```swift theme={null}
struct AuthSession
```

## Instance Properties

| Property | Type       | Description |
| -------- | ---------- | ----------- |
| `jwt`    | `String`   | -           |
| `user`   | `AuthUser` | -           |


# AuthUser
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/authuser

Swift Structure

**Structure**

```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 }
```


# BalanceTransformer
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/balancetransformer

Swift Structure

**Structure**

```swift theme={null}
struct BalanceTransformer
```

## Type Methods

### transform(from:nativeToken:requestedTokens:)

```swift theme={null}
static func transform(from balances: Balances, nativeToken: CryptoCurrency, requestedTokens: [CryptoCurrency]) -> Balance
```


# 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?
```

### merge(with:)

```swift theme={null}
func merge(with other: ChainBalances?) -> ChainBalances
```

## 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?`                | -           |
| `status`    | `String?`                | -           |


# 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:)

```swift theme={null}
init(transaction: String)
```

## Instance Properties

| Property      | Type     | Description |
| ------------- | -------- | ----------- |
| `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:)

```swift theme={null}
init(transaction: String)
```

## Instance Properties

| Property      | Type     | Description |
| ------------- | -------- | ----------- |
| `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` | `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(withService:)

Inherited from `TransactionApiModel.toDomain(withService:)`.

```swift theme={null}
func toDomain(withService _: any SmartWalletService) -> Transaction?
```


# 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)
```


# ListTransfersQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/listtransfersqueryparams

Swift Structure

**Structure**

```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`            | -           |
| `tokens`        | `[CryptoCurrency]` | -           |
| `walletLocator` | `WalletLocator`    | -           |


# 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**

```swift theme={null}
struct OTPRequest
```

## Instance Properties

| Property    | Type     | Description                       |
| ----------- | -------- | --------------------------------- |
| `id`        | `String` | Inherited from `Identifiable.id`. |
| `requestId` | `String` | -                                 |


# 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`.      |


# 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**

```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` | -           |


# 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`                      | -           |


# SmartWalletConfigRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/smartwalletconfigrequest

Swift Structure

**Structure**

```swift theme={null}
struct SmartWalletConfigRequest
```

## Initializers

### init(chain:)

```swift theme={null}
init(chain: Chain)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# 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(withService:)

Inherited from `TransactionApiModel.toDomain(withService:)`.

```swift theme={null}
func toDomain(withService _: any SmartWalletService) -> 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(withService:)

Inherited from `TransactionApiModel.toDomain(withService:)`.

```swift theme={null}
func toDomain(withService _: any SmartWalletService) -> 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
```


# 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:)

```swift theme={null}
init(symbol: TokenBalance.Symbol, name: String, amount: String, contractAddress: String? = nil, decimals: Int? = nil, rawAmount: String? = nil)
```

## Instance Properties

| Property          | Type                  | Description |
| ----------------- | --------------------- | ----------- |
| `amount`          | `String`              | -           |
| `contractAddress` | `String?`             | -           |
| `decimals`        | `Int?`                | -           |
| `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**

```swift theme={null}
struct TransactionSummary
```

## Instance Properties

| Property        | Type     | Description |
| --------------- | -------- | ----------- |
| `explorerLink`  | `URL`    | -           |
| `hash`          | `String` | -           |
| `transactionID` | `String` | -           |


# Transfer
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transfer

Swift Structure

**Structure**

```swift theme={null}
struct Transfer
```

## 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`      | -                                 |
| `fromAddress`     | `String`       | -                                 |
| `id`              | `String`       | Inherited from `Identifiable.id`. |
| `mintHash`        | `String?`      | -                                 |
| `rawAmount`       | `String`       | -                                 |
| `timestamp`       | `Date`         | -                                 |
| `toAddress`       | `String`       | -                                 |
| `tokenSymbol`     | `String?`      | -                                 |
| `transactionHash` | `String`       | -                                 |
| `type`            | `TransferType` | -                                 |


# TransferListResult
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transferlistresult

Swift Structure

**Structure**

```swift theme={null}
struct TransferListResult
```

## Initializers

### init(transfers:)

```swift theme={null}
init(transfers: [Transfer])
```

## Instance Properties

| Property    | Type         | Description |
| ----------- | ------------ | ----------- |
| `transfers` | `[Transfer]` | -           |


# 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`. |


# UnknownApiTransaction
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/unknownapitransaction

Swift Structure

**Structure**

```swift theme={null}
struct UnknownApiTransaction
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type     | Description                       |
| -------- | -------- | --------------------------------- |
| `id`     | `String` | Inherited from `Identifiable.id`. |

## Instance Methods

### toDomain(withService:)

Inherited from `TransactionApiModel.toDomain(withService:)`.

```swift theme={null}
func toDomain(withService service: any SmartWalletService) -> Transaction?
```


# 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` | -           |


# 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 |
| ---------- | ---------------------------------------- | ----------- |
| `recovery` | `any AdminSignerApiModel`                | -           |
| `signers`  | `[WalletDelegatedSignerConfigApiModel]?` | -           |


# WalletDelegatedSignerConfigApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletdelegatedsignerconfigapimodel

Swift Structure

**Structure**

```swift theme={null}
struct WalletDelegatedSignerConfigApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property  | Type      | Description |
| --------- | --------- | ----------- |
| `locator` | `String?` | -           |
| `signer`  | `String?` | -           |


# WalletOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletoptions

Swift Structure

**Structure**

```swift theme={null}
struct WalletOptions
```

## Initializers

### init(deviceSigner:)

```swift theme={null}
init(deviceSigner: Bool = false)
```

## Instance Properties

| Property       | Type   | Description |
| -------------- | ------ | ----------- |
| `deviceSigner` | `Bool` | -           |


# 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `message`            | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/CrossmintWallets) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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.
Either a signer or recovery must be provided.
If no signer is provided but recovery is set, the wallet will be read-only.

#### 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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.


# EVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/EVMWallet



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/EVMWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                                                                                   |
| --------------- | --------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `address` | `string`              | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L85) |
| <a /> `alias?`  | `string`              | [`Wallet`](./Wallet).[`alias`](./Wallet#alias)     | [packages/wallets/src/wallets/wallet.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L87) |
| <a /> `chain`   | `EVMSmartWalletChain` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain)     | [packages/wallets/src/wallets/wallet.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L84) |
| <a /> `owner?`  | `string`              | [`Wallet`](./Wallet).[`owner`](./Wallet#owner)     | [packages/wallets/src/wallets/wallet.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L86) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:262](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L262)

##### 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:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L286)

**`Experimental`**

Get the recovery signer config

##### 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)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L167)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### 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:601](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L601)

Add a signer to the wallet.
Always uses the recovery signer internally to approve the registration.
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`   | [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`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:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

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:530](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L530)

#### 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:303](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L303)

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* 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 `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* 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` \| `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* 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),
})
```

***

### isSignerApproved()

> **isSignerApproved**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:970](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L970)

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

#### Inherited from

[`Wallet`](./Wallet).[`isSignerApproved`](./Wallet#issignerapproved)

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:978](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L978)

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:372](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L372)

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:994](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L994)

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)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:761](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L761)

Remove a signer from the wallet.
Always uses the recovery signer internally to approve the removal.

#### Type Parameters

| Type Parameter                                                                            | Default type |
| ----------------------------------------------------------------------------------------- | ------------ |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined`  |

#### Parameters

| Parameter  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Description                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `signer`   | [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`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:447](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L447)

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:961](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L961)

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:1011](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1011)

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:342](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L342)

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:404](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L404)

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:391](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L391)

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:419](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L419)

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)

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:819](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L819)

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`  | [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`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:175](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L175)

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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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)


# InvalidTransferAmountError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/InvalidTransferAmountError



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/utils/errors.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L166)

## Extends

* `CrossmintSDKError`

## Constructors

### new InvalidTransferAmountError()

> **new InvalidTransferAmountError**(`message`, `details`?): `InvalidTransferAmountError`

Defined in: [packages/wallets/src/utils/errors.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L167)

#### Parameters

| Parameter  | Type     |
| ---------- | -------- |
| `message`  | `string` |
| `details`? | `string` |

#### Returns

`InvalidTransferAmountError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property                   | Modifier   | Type                                                    | Description                                                                                                                                                                        | Inherited from                        | Defined in                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.code`              | packages/common/base/dist/error/index.d.ts:4                                         |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.details`           | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | -                                                                                                          | packages/common/base/dist/error/index.d.ts:22                                        |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details)                     | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message)                     | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name)                           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack)                         | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | -                                                                                                          | packages/common/base/dist/error/index.d.ts:12                                        |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details)                     | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `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                                        |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message)                     | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name)                           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack)                         | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | -                                                                                                          | packages/common/base/dist/error/index.d.ts:26                                        |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details)                     | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `identifierKey?`     | `readonly` | `string`                                                | -                                                                                                                                                                                  | -                                                                                | -                                                                                                          | packages/common/base/dist/error/index.d.ts:27                                        |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message)                     | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name)                           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack)                         | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | -                                                                                                          | packages/common/base/dist/error/index.d.ts:18                                        |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details)                     | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message)                     | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name)                           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | -                                                                                | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack)                         | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/signers/types.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L60)

## Extends

* `Error`

## Constructors

### new KeyExportError()

> **new KeyExportError**(`message`, `code`?): `KeyExportError`

Defined in: [packages/wallets/src/signers/types.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L63)

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `message` | `string` |
| `code`?   | `string` |

#### Returns

`KeyExportError`

#### Overrides

`Error.constructor`

## Properties

| Property                   | Modifier   | Type                                                    | Description                                                                                                                                                                        | Inherited from            | Defined in                                                                                                                                 |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string` \| `undefined`                                 | -                                                                                                                                                                                  | -                         | [packages/wallets/src/signers/types.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L61) |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077                                                       |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076                                                       |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078                                                       |
| <a /> `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                                                         |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.code`              | packages/common/base/dist/error/index.d.ts:4                                         |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.details`           | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/signers/types.ts:75](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L75)

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:76](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L76)

#### 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                                                                           |
| -------------------------- | -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `message`            | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public` | `string`                                                | -                                                                                                                                                                                  | `Error.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                                                                                 |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <a /> `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) |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077                                                       |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076                                                       |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078                                                       |
| <a /> `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                                                         |
| <a /> `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`


# SignerStatusError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/SignerStatusError



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/signers/types.ts:50](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L50)

## Extends

* `Error`

## Constructors

### new SignerStatusError()

> **new SignerStatusError**(`message`, `code`?): `SignerStatusError`

Defined in: [packages/wallets/src/signers/types.ts:53](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L53)

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `message` | `string` |
| `code`?   | `string` |

#### Returns

`SignerStatusError`

#### Overrides

`Error.constructor`

## Properties

| Property                   | Modifier   | Type                                                    | Description                                                                                                                                                                        | Inherited from            | Defined in                                                                                                                                 |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string` \| `undefined`                                 | -                                                                                                                                                                                  | -                         | [packages/wallets/src/signers/types.ts:51](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L51) |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077                                                       |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076                                                       |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `Error.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078                                                       |
| <a /> `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                                                         |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/SolanaWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                                                                                   |
| --------------- | ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `address` | `string`   | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L85) |
| <a /> `alias?`  | `string`   | [`Wallet`](./Wallet).[`alias`](./Wallet#alias)     | [packages/wallets/src/wallets/wallet.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L87) |
| <a /> `chain`   | `"solana"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain)     | [packages/wallets/src/wallets/wallet.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L84) |
| <a /> `owner?`  | `string`   | [`Wallet`](./Wallet).[`owner`](./Wallet#owner)     | [packages/wallets/src/wallets/wallet.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L86) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:262](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L262)

##### 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:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L286)

**`Experimental`**

Get the recovery signer config

##### 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)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L167)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### 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:601](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L601)

Add a signer to the wallet.
Always uses the recovery signer internally to approve the registration.
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`   | [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

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:530](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L530)

#### 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:303](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L303)

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:970](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L970)

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

#### Inherited from

[`Wallet`](./Wallet).[`isSignerApproved`](./Wallet#issignerapproved)

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:978](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L978)

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:372](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L372)

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:994](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L994)

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)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:761](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L761)

Remove a signer from the wallet.
Always uses the recovery signer internally to approve the removal.

#### Type Parameters

| Type Parameter                                                                            | Default type |
| ----------------------------------------------------------------------------------------- | ------------ |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined`  |

#### Parameters

| Parameter  | Type                                                                                                                                                                                                                                                                                                            | Description                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `signer`   | [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:447](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L447)

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:56](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L56)

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:961](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L961)

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:1011](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1011)

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:342](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L342)

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:404](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L404)

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:391](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L391)

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:419](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L419)

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)

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:819](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L819)

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`  | [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:175](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L175)

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:36](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L36)

#### Parameters

| Parameter | Type                                                    |
| --------- | ------------------------------------------------------- |
| `wallet`  | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`SolanaWallet`


# StellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/StellarWallet



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/StellarWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                                                                                   |
| --------------- | ----------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `address` | `string`    | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L85) |
| <a /> `alias?`  | `string`    | [`Wallet`](./Wallet).[`alias`](./Wallet#alias)     | [packages/wallets/src/wallets/wallet.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L87) |
| <a /> `chain`   | `"stellar"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain)     | [packages/wallets/src/wallets/wallet.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L84) |
| <a /> `owner?`  | `string`    | [`Wallet`](./Wallet).[`owner`](./Wallet#owner)     | [packages/wallets/src/wallets/wallet.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L86) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:262](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L262)

##### 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:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L286)

**`Experimental`**

Get the recovery signer config

##### 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)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L167)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### 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:601](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L601)

Add a signer to the wallet.
Always uses the recovery signer internally to approve the registration.
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`   | [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

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:530](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L530)

#### 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:303](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L303)

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:970](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L970)

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

#### 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:978](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L978)

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:372](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L372)

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:994](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L994)

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)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:761](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L761)

Remove a signer from the wallet.
Always uses the recovery signer internally to approve the removal.

#### Type Parameters

| Type Parameter                                                                            | Default type |
| ----------------------------------------------------------------------------------------- | ------------ |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined`  |

#### Parameters

| Parameter  | Type                                                                                                                                                                                                                                                                                                             | Description                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `signer`   | [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:447](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L447)

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:961](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L961)

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:1011](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1011)

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:342](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L342)

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:404](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L404)

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:391](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L391)

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:419](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L419)

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.

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:819](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L819)

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`  | [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| `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:175](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L175)

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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/utils/errors.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L106)

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:107](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L107)

#### Parameters

| Parameter  | Type     |
| ---------- | -------- |
| `message`  | `string` |
| `details`? | `string` |

#### Returns

`UnsupportedBrowserError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property                   | Modifier   | Type                                                    | Description                                                                                                                                                                        | Inherited from                        | Defined in                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.code`              | packages/common/base/dist/error/index.d.ts:4                                         |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.details`           | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.message`           | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.name`              | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.stack`             | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/Wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/wallets/wallet.ts:83](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L83)

## 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:98](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L98)

#### Parameters

| Parameter   | Type                                     |
| ----------- | ---------------------------------------- |
| `args`      | `WalletContructorType`\<`C`>             |
| `apiClient` | [`WalletsApiClient`](./WalletsApiClient) |

#### Returns

`Wallet`\<`C`>

## Properties

| Property        | Type     | Defined in                                                                                                                                   |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `address` | `string` | [packages/wallets/src/wallets/wallet.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L85) |
| <a /> `alias?`  | `string` | [packages/wallets/src/wallets/wallet.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L87) |
| <a /> `chain`   | `C`      | [packages/wallets/src/wallets/wallet.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L84) |
| <a /> `owner?`  | `string` | [packages/wallets/src/wallets/wallet.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L86) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:262](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L262)

##### Returns

[`WalletsApiClient`](./WalletsApiClient)

***

### recovery

#### Get Signature

> **get** **recovery**(): [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L286)

**`Experimental`**

Get the recovery signer config

##### Returns

[`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

The recovery signer config
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:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L167)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

## Methods

### addSigner()

> **addSigner**\<`T`>(`signer`, `options`?): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `AddSignerReturnType`\<`C`> : [`Signer`](../type-aliases/Signer)>

Defined in: [packages/wallets/src/wallets/wallet.ts:601](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L601)

Add a signer to the wallet.
Always uses the recovery signer internally to approve the registration.
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:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

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:530](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L530)

#### 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:303](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L303)

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:970](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L970)

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

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:978](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L978)

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:372](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L372)

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:994](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L994)

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`>

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:761](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L761)

Remove a signer from the wallet.
Always uses the recovery signer internally to approve the removal.

#### 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:447](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L447)

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:961](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L961)

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:1011](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1011)

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:342](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L342)

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:404](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L404)

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:391](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L391)

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:419](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L419)

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

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:819](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L819)

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:175](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L175)

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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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                                                                           |
| -------------------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a /> `code`               | `readonly` | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.code`                                                                                       | packages/common/base/dist/error/index.d.ts:4                                         |
| <a /> `details?`           | `readonly` | `string`                                                | -                                                                                                                                                                                  | [`InvalidTransferAmountError`](./InvalidTransferAmountError).[`details`](./InvalidTransferAmountError#details) | packages/common/base/dist/error/index.d.ts:5                                         |
| <a /> `message`            | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.message`                                                                                    | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a /> `name`               | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.name`                                                                                       | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a /> `stack?`             | `public`   | `string`                                                | -                                                                                                                                                                                  | `CrossmintSDKError.stack`                                                                                      | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a /> `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   |
| <a /> `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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/classes/WalletsApiClient) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/api/client.ts:42](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L42)

## Extends

* `CrossmintApiClient`

## Constructors

### new WalletsApiClient()

> **new WalletsApiClient**(`crossmint`): `ApiClient`

Defined in: [packages/wallets/src/api/client.ts:46](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L46)

#### Parameters

| Parameter   | Type        |
| ----------- | ----------- |
| `crossmint` | `Crossmint` |

#### Returns

`ApiClient`

#### Overrides

`CrossmintApiClient.constructor`

## Properties

| Property          | Type        | Inherited from                 | Defined in                                                     |
| ----------------- | ----------- | ------------------------------ | -------------------------------------------------------------- |
| <a /> `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:297](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L297)

##### Returns

`APIKeyEnvironmentPrefix`

#### Overrides

`CrossmintApiClient.environment`

***

### isServerSide

#### Get Signature

> **get** **isServerSide**(): `boolean`

Defined in: [packages/wallets/src/api/client.ts:293](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L293)

##### Returns

`boolean`

***

### projectId

#### Get Signature

> **get** **projectId**(): `string`

Defined in: [packages/wallets/src/api/client.ts:304](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L304)

##### Returns

`string`

## Methods

### approveSignature()

> **approveSignature**(`walletLocator`, `signatureId`, `params`): `Promise`\<`ApproveSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:141](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L141)

#### 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:111](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L111)

#### 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:130](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L130)

#### Parameters

| Parameter       | Type                      |
| --------------- | ------------------------- |
| `walletLocator` | `string`                  |
| `params`        | `CreateSignatureV2025Dto` |

#### Returns

`Promise`\<`CreateSignatureResponse`>

***

### createTransaction()

> **createTransaction**(`walletLocator`, `params`): `Promise`\<`CreateTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:100](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L100)

#### Parameters

| Parameter       | Type                             |
| --------------- | -------------------------------- |
| `walletLocator` | `string`                         |
| `params`        | `CreateTransactionV2025DtoClass` |

#### Returns

`Promise`\<`CreateTransactionResponse`>

***

### createWallet()

> **createWallet**(`params`): `Promise`\<`CreateWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:54](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L54)

#### 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:223](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L223)

#### 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:207](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L207)

#### 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:172](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L172)

#### 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:158](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L158)

#### Parameters

| Parameter       | Type     |
| --------------- | -------- |
| `walletLocator` | `string` |
| `signatureId`   | `string` |

#### Returns

`Promise`\<`GetSignatureResponse`>

***

### getSigner()

> **getSigner**(`walletLocator`, `signer`): `Promise`\<`GetSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:259](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L259)

#### Parameters

| Parameter       | Type     |
| --------------- | -------- |
| `walletLocator` | `string` |
| `signer`        | `string` |

#### Returns

`Promise`\<`GetSignerResponse`>

***

### getTransaction()

> **getTransaction**(`walletLocator`, `transactionId`): `Promise`\<`GetTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:123](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L123)

#### Parameters

| Parameter       | Type     |
| --------------- | -------- |
| `walletLocator` | `string` |
| `transactionId` | `string` |

#### Returns

`Promise`\<`GetTransactionResponse`>

***

### getTransactions()

> **getTransactions**(`walletLocator`): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/api/client.ts:165](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L165)

#### Parameters

| Parameter       | Type     |
| --------------- | -------- |
| `walletLocator` | `string` |

#### Returns

`Promise`\<`GetTransactionsResponse`>

***

### getTransfers()

> **getTransfers**(`walletLocator`, `params`): `Promise`\<`GetTransfersResponse`>

Defined in: [packages/wallets/src/api/client.ts:188](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L188)

#### 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:80](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L80)

#### 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`

***

### registerSigner()

> **registerSigner**(`walletLocator`, `params`): `Promise`\<`RegisterSignerResponse`>

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`               |
| `params`        | `RegisterSignerParams` |

#### Returns

`Promise`\<`RegisterSignerResponse`>

***

### removeSigner()

> **removeSigner**(`walletLocator`, `signer`, `params`): `Promise`\<`RemoveSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:242](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L242)

#### 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:267](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L267)

#### 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/functions/createCrossmint) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **isExportableSignerAdapter**(`signer`): `signer is ExportableSignerAdapter`

Defined in: [packages/wallets/src/signers/types.ts:282](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L282)

## Parameters

| Parameter | Type                                           |
| --------- | ---------------------------------------------- |
| `signer`  | [`SignerAdapter`](../interfaces/SignerAdapter) |

## Returns

`signer is ExportableSignerAdapter`


# ExportableSignerAdapter
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/interfaces/ExportableSignerAdapter



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/signers/types.ts:275](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L275)

## Extends

* [`SignerAdapter`](./SignerAdapter)

## Properties

### \_exportPrivateKey()

> **\_exportPrivateKey**: (`exportTEEConnection`, `onExport`?) => `Promise`\<`void`>

Defined in: [packages/wallets/src/signers/types.ts:276](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L276)

#### 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:268](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L268)

#### Inherited from

[`ExportableSignerAdapter`](./).[`status`](./#status)

***

### type

> **type**: keyof `SignResultMap`

Defined in: [packages/wallets/src/signers/types.ts:267](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L267)

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`type`](./SignerAdapter#type)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:270](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L270)

#### Returns

`string`

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`address`](./SignerAdapter#address)

***

### locator()

> **locator**(): [`SignerLocator`](../type-aliases/SignerLocator)

Defined in: [packages/wallets/src/signers/types.ts:269](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L269)

#### 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:271](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L271)

#### 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:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L272)

#### 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Defined in: [packages/wallets/src/signers/types.ts:266](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L266)

## 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:268](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L268)

***

### type

> **type**: `T`

Defined in: [packages/wallets/src/signers/types.ts:267](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L267)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:270](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L270)

#### Returns

`string`

***

### locator()

> **locator**(): [`SignerLocator`](../type-aliases/SignerLocator)

Defined in: [packages/wallets/src/signers/types.ts:269](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L269)

#### Returns

[`SignerLocator`](../type-aliases/SignerLocator)

***

### signMessage()

> **signMessage**(`message`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:271](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L271)

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `message` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>

***

### signTransaction()

> **signTransaction**(`transaction`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L272)

#### Parameters

| Parameter     | Type     |
| ------------- | -------- |
| `transaction` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>


# Getting Started
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/overview



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

### 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",
  recovery: { 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 the recovery signer:

```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",
  recovery: { 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",
  recovery: {
    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",
  recovery: { 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 signer** — 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 signer 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 signer.                                                             | All                   |
| `phone`           | OTP-based recovery signer.                                                             | 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/reference) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## Classes

* [AuthRejectedError](./classes/AuthRejectedError)
* [CrossmintWallets](./classes/CrossmintWallets)
* [DeviceSignerKeyStorage](./classes/DeviceSignerKeyStorage)
* [EVMWallet](./classes/EVMWallet)
* [IframeDeviceSignerKeyStorage](./classes/IframeDeviceSignerKeyStorage)
* [InvalidTransferAmountError](./classes/InvalidTransferAmountError)
* [JWTDecryptionError](./classes/JWTDecryptionError)
* [JWTExpiredError](./classes/JWTExpiredError)
* [JWTIdentifierError](./classes/JWTIdentifierError)
* [JWTInvalidError](./classes/JWTInvalidError)
* [KeyExportError](./classes/KeyExportError)
* [NotAuthorizedError](./classes/NotAuthorizedError)
* [OnboardingSessionExpiredError](./classes/OnboardingSessionExpiredError)
* [OtpValidationError](./classes/OtpValidationError)
* [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

* [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)
* [RegisterSignerPasskeyParams](./type-aliases/RegisterSignerPasskeyParams)
* [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)


# AddSignerOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/AddSignerOptions



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ApiKeySignerLocator** = `"api-key"` | `` `api-key:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:241](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L241)


# ApproveOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ApproveOptions



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ApproveOptions** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:309](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L309)

## Properties

### additionalSigners?

> `optional` **additionalSigners**: [`SignerAdapter`](../interfaces/SignerAdapter)\[]

Defined in: [packages/wallets/src/wallets/types.ts:311](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L311)

***

### approval?

> `optional` **approval**: `Approval`

Defined in: [packages/wallets/src/wallets/types.ts:310](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L310)


# ApproveParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ApproveParams



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ApproveParams** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:314](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L314)

## Properties

### options?

> `optional` **options**: [`ApproveOptions`](./ApproveOptions)

Defined in: [packages/wallets/src/wallets/types.ts:317](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L317)

***

### signatureId?

> `optional` **signatureId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:316](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L316)

***

### transactionId?

> `optional` **transactionId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:315](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L315)


# Balances
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Balances



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/Balances) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Balances**\<`C`> = `object`

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                   | Default type       |
| -------------------------------- | ------------------ |
| `C` *extends* [`Chain`](./Chain) | [`Chain`](./Chain) |

## Properties

### nativeToken

> **nativeToken**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:275](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L275)

***

### tokens

> **tokens**: `TokenBalance`\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:277](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L277)

***

### usdc

> **usdc**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:276](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L276)


# BiometricRequestHandler
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/BiometricRequestHandler



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Callbacks** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:199](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L199)

## Properties

### onAuthRequired()?

> `optional` **onAuthRequired**: (`signerType`, `signerLocator`, `needsAuth`, `sendOtp`, `verifyOtp`, `reject`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:202](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L202)

#### 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:201](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L201)

#### Returns

`Promise`\<`void`>

***

### onWalletCreationStart()?

> `optional` **onWalletCreationStart**: () => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:200](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L200)

#### Returns

`Promise`\<`void`>


# Chain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Chain



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/Chain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Chain** = [`SolanaChain`](./SolanaChain) | [`EVMChain`](./EVMChain) | [`StellarChain`](./StellarChain)

Defined in: [packages/wallets/src/chains/chains.ts:161](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L161)


# ClientSideWalletArgsFor
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ClientSideWalletArgsFor



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ClientSideWalletArgsFor**\<`C`> = `Omit`\<[`WalletArgsFor`](./WalletArgsFor)\<`C`>, `"owner"`>

Defined in: [packages/wallets/src/wallets/types.ts:254](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L254)

## Type Parameters

| Type Parameter                   |
| -------------------------------- |
| `C` *extends* [`Chain`](./Chain) |


# ClientSideWalletCreateArgs
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ClientSideWalletCreateArgs



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ClientSideWalletCreateArgs**\<`C`> = `Omit`\<[`WalletCreateArgs`](./WalletCreateArgs)\<`C`>, `"owner"`>

Defined in: [packages/wallets/src/wallets/types.ts:256](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L256)

## Type Parameters

| Type Parameter                   |
| -------------------------------- |
| `C` *extends* [`Chain`](./Chain) |


# CreateServerSignerParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/CreateServerSignerParams



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **DeviceSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:220](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L220)

## Properties

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:223](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L223)

***

### name?

> `optional` **name**: `string`

Defined in: [packages/wallets/src/signers/types.ts:224](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L224)

***

### publicKey?

> `optional` **publicKey**: `object`

Defined in: [packages/wallets/src/signers/types.ts:222](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L222)

#### x

> **x**: `string`

#### y

> **y**: `string`

***

### type

> **type**: `"device"`

Defined in: [packages/wallets/src/signers/types.ts:221](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L221)


# DeviceSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/DeviceSignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **DeviceSignerLocator** = `` `device:${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)


# EVMChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EVMChain



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/EVMChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **EVMChain** = `EVMSmartWalletChain`

Defined in: [packages/wallets/src/chains/chains.ts:159](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L159)


# EVMTransactionInput
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EVMTransactionInput



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/EVMTransactionInput) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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:82](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L82)


# EmailSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EmailSignerConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/EmailSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **EmailSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:81](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L81)

## Properties

### email?

> `optional` **email**: `string`

Defined in: [packages/wallets/src/signers/types.ts:83](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L83)

***

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L84)

***

### type

> **type**: `"email"`

Defined in: [packages/wallets/src/signers/types.ts:82](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L82)


# EmailSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EmailSignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **EmailSignerLocator** = `` `email:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:236](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L236)


# EvmExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EvmExternalWalletSignerConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/EvmExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **EvmExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:13

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:15

***

### onSign()

> **onSign**: (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:16

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `payload` | `string` |

#### Returns

`Promise`\<`string`>

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:14


# ExportSignerTEEConnection
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExportSignerTEEConnection



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/ExportSignerTEEConnection) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ExportSignerTEEConnection** = `HandshakeParent`\<*typeof* `exportSignerOutboundEvents`, *typeof* `exportSignerInboundEvents`>

Defined in: [packages/wallets/src/signers/types.ts:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L286)


# ExternalWalletRegistrationConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletRegistrationConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/ExternalWalletSignerConfigForChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ExternalWalletSignerConfigForChain**\<`C`> = `C` *extends* [`SolanaChain`](./SolanaChain) ? [`SolanaExternalWalletSignerConfig`](./SolanaExternalWalletSignerConfig) : `C` *extends* [`StellarChain`](./StellarChain) ? [`StellarExternalWalletSignerConfig`](./StellarExternalWalletSignerConfig) : [`EvmExternalWalletSignerConfig`](./EvmExternalWalletSignerConfig)

Defined in: [packages/wallets/src/signers/types.ts:95](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L95)

## Type Parameters

| Type Parameter                   |
| -------------------------------- |
| `C` *extends* [`Chain`](./Chain) |


# ExternalWalletSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletSignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ExternalWalletSignerLocator** = `` `external-wallet:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:240](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L240)


# PasskeySignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PasskeySignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **PasskeySignerLocator** = `` `passkey:${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)


# PhoneSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PhoneSignerConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/PhoneSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **PhoneSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L87)

## Properties

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:90](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L90)

***

### phone?

> `optional` **phone**: `string`

Defined in: [packages/wallets/src/signers/types.ts:89](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L89)

***

### type

> **type**: `"phone"`

Defined in: [packages/wallets/src/signers/types.ts:88](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L88)


# PhoneSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PhoneSignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **PhoneSignerLocator** = `` `phone:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:237](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L237)


# RegisterSignerPasskeyParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RegisterSignerPasskeyParams



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **RegisterSignerPasskeyParams** = `Extract`\<`CreateSignerV2025InputDtoClass`\[`"signer"`], \{ `type`: `"passkey"`; }>

Defined in: [packages/wallets/src/api/types.ts:80](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L80)


# RemoveSignerOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RemoveSignerOptions



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Scope** = [`TransferScope`](./TransferScope)

Defined in: [packages/wallets/src/api/types.ts:93](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L93)


# ServerSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ServerSigner



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **ServerSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L103)

## Properties

### secret

> **secret**: `string`

Defined in: [packages/wallets/src/signers/types.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L105)

***

### type

> **type**: `"server"`

Defined in: [packages/wallets/src/signers/types.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L104)


# Signature
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Signature



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/Signature) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Signature**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:299](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L299)

## Type Parameters

| Type Parameter                     | Default type |
| ---------------------------------- | ------------ |
| `TPrepareOnly` *extends* `boolean` | `false`      |


# Signer
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Signer



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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`; `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:138](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L138)


# SignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerConfigForChain



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/SignerConfigForChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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:227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L227)

## Type Parameters

| Type Parameter                   |
| -------------------------------- |
| `C` *extends* [`Chain`](./Chain) |


# SignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerLocator



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **SignerLocator** = [`EmailSignerLocator`](./EmailSignerLocator) | [`PhoneSignerLocator`](./PhoneSignerLocator) | [`PasskeySignerLocator`](./PasskeySignerLocator) | [`DeviceSignerLocator`](./DeviceSignerLocator) | [`ExternalWalletSignerLocator`](./ExternalWalletSignerLocator) | [`ApiKeySignerLocator`](./ApiKeySignerLocator) | `ServerSignerLocator`

Defined in: [packages/wallets/src/signers/types.ts:244](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L244)


# SignerStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerStatus



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **SignerStatus** = `"success"` | `"active"` | `"pending"` | `"awaiting-approval"` | `"failed"`

Defined in: [packages/wallets/src/wallets/types.ts:130](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L130)


# SolanaChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SolanaChain



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/SolanaChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **SolanaChain** = `"solana"`

Defined in: [packages/wallets/src/chains/chains.ts:157](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L157)


# SolanaExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SolanaExternalWalletSignerConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/SolanaExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **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`>

***

### 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/SolanaTransactionInput) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **SolanaTransactionInput** = \{ `transaction`: `VersionedTransaction`; } | \{ `serializedTransaction`: `string`; } & `object`

Defined in: [packages/wallets/src/wallets/types.ts:110](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L110)

## Type Declaration

### additionalSigners?

> `optional` **additionalSigners**: `Keypair`\[]

### options?

> `optional` **options**: `TransactionInputOptions`


# StellarChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/StellarChain



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/StellarChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **StellarChain** = `"stellar"`

Defined in: [packages/wallets/src/chains/chains.ts:158](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L158)


# StellarExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/StellarExternalWalletSignerConfig



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/StellarExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **StellarExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:18

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:20

***

### onSign()

> **onSign**: (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:21

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `payload` | `string` |

#### Returns

`Promise`\<`string`>

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:19


# Transaction
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Transaction



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/Transaction) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Transaction**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:287](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L287)

## Type Parameters

| Type Parameter                     | Default type |
| ---------------------------------- | ------------ |
| `TPrepareOnly` *extends* `boolean` | `false`      |


# TransferScope
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/TransferScope



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **TransferScope** = `object`

Defined in: [packages/wallets/src/api/types.ts:82](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L82)

## Properties

### recipients?

> `optional` **recipients**: `string`\[]

Defined in: [packages/wallets/src/api/types.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L85)

***

### spendingLimit?

> `optional` **spendingLimit**: `object`

Defined in: [packages/wallets/src/api/types.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L86)

#### 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:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L84)

***

### type

> **type**: `"transfer"`

Defined in: [packages/wallets/src/api/types.ts:83](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L83)


# Transfers
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Transfers



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **Transfers** = `WalletsActivityResponseUnstableDto`

Defined in: [packages/wallets/src/api/types.ts:75](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L75)


# WalletArgsFor
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletArgsFor



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/WalletArgsFor) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **WalletArgsFor**\<`C`> = `object`

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) |

## Properties

### alias?

> `optional` **alias**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:232](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L232)

Optional wallet alias.

***

### chain

> **chain**: `C`

Defined in: [packages/wallets/src/wallets/types.ts:225](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L225)

The blockchain to create the wallet on (e.g. "base-sepolia").

***

### options?

> `optional` **options**: [`WalletOptions`](./WalletOptions)

Defined in: [packages/wallets/src/wallets/types.ts:230](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L230)

***

### owner?

> `optional` **owner**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L227)

Optional owner identifier.

***

### plugins?

> `optional` **plugins**: [`WalletPlugin`](./WalletPlugin)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:229](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L229)

Optional array of wallet plugins.


# WalletCreateArgs
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletCreateArgs



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **WalletCreateArgs**\<`C`> = [`WalletArgsFor`](./WalletArgsFor)\<`C`> & `object`

Defined in: [packages/wallets/src/wallets/types.ts:235](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L235)

## Type Declaration

### alias?

> `optional` **alias**: `string`

### recovery

> **recovery**: `Exclude`\<[`SignerConfigForChain`](./SignerConfigForChain)\<`C`>, [`DeviceSignerConfig`](./DeviceSignerConfig)>

Recovery signer for wallet creation. Device signers cannot be recovery signers.

### 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



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **WalletOptions** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:216](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L216)

## Properties

### callbacks?

> `optional` **callbacks**: [`Callbacks`](./Callbacks)

Defined in: [packages/wallets/src/wallets/types.ts:217](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L217)

***

### clientTEEConnection?

> `optional` **clientTEEConnection**: `HandshakeParent`\<*typeof* `signerOutboundEvents`, *typeof* `signerInboundEvents`>

Defined in: [packages/wallets/src/wallets/types.ts:218](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L218)

***

### deviceSignerKeyStorage?

> `optional` **deviceSignerKeyStorage**: `DeviceSignerKeyStorage`

Defined in: [packages/wallets/src/wallets/types.ts:220](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L220)

***

### resetSignerFrame()?

> `optional` **resetSignerFrame**: () => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:219](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L219)

#### Returns

`Promise`\<`void`>


# WalletPlugin
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletPlugin



<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/sdk-reference/wallets/v0/typescript/type-aliases/WalletPlugin) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

> **WalletPlugin**\<`C`> = `C` *extends* [`StellarChain`](./StellarChain) ? `StellarWalletPlugin` : `never`

Defined in: [packages/wallets/src/wallets/types.ts:214](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L214)

## 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                                                                                                                                   |
| --------------- | -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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                                                                                                                                   |
| --------------- | -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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                                                                                                                                   |
| --------------- | -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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) |
| <a /> `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                                                                                                                                   |
| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <a /> `address` | `string`                         | [packages/wallets/src/wallets/wallet.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L62) |
| <a /> `alias?`  | `string`                         | [packages/wallets/src/wallets/wallet.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L64) |
| <a /> `chain`   | `C`                              | [packages/wallets/src/wallets/wallet.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L61) |
| <a /> `owner?`  | `string`                         | [packages/wallets/src/wallets/wallet.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L63) |
| <a /> `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                                                     |
| ----------------- | ----------- | ------------------------------ | -------------------------------------------------------------- |
| <a /> `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? Our support team 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

*Integration guide coming soon. [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're 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 manages the entire flow including payment processing, fraud prevention, chargebacks, currency conversion, KYC/AML, and regulatory compliance. Best for teams who want a plug-and-play solution, want to reduce their chargeback exposure, or don't 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/concepts/wallet-extensions).

### 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/concepts/wallet-extensions">
    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? Our team 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**: Accept fiat deposits, 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? Our team 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

*Integration guide coming soon. [Contact our sales team](https://www.crossmint.com/contact/sales) to request a consultation to help you design and integrate.*


# Example Workflows
Source: https://docs.crossmint.com/solutions/n8n/example-workflows

Ready-to-use workflow templates to get you started

These ready-to-use examples live in the `workflows-examples/` folder of the [GitHub repository](https://github.com/crossmint/n8n-nodes-crossmint).

## Buy Celsius

**File**: `buy-celsius.json`

This workflow demonstrates the complete wallet lifecycle and checkout process:

* Create or retrieve a wallet
* Get wallet details
* Check wallet balance
* Create and pay for an order

<img alt="Crossmint nodes examples" />

<Card title="Download workflow" icon="download" href="https://github.com/crossmint/n8n-nodes-crossmint/blob/main/workflows-examples/buy-celsius.json">
  Import this workflow into your n8n instance
</Card>

## Buy Any Item from Amazon or Shopify Using Natural Language

**File**: `buy-items-amazon.json`

An advanced workflow that combines AI and automation:

1. Receives product requests in natural language
2. Uses OpenAI to parse and extract product details
3. Automatically purchases items from Amazon using stablecoins

<img alt="Buy items from Amazon workflow" />

<Card title="Download workflow" icon="download" href="https://github.com/crossmint/n8n-nodes-crossmint/blob/main/workflows-examples/buy-items-amazon.json">
  Import this workflow into your n8n instance
</Card>

## How to Use These Workflows

<Steps>
  <Step title="Download the workflow JSON">
    Click the download link for the workflow you want to use
  </Step>

  <Step title="Import into n8n">
    In n8n, go to **Create Workflow**, in the top right select the **options menu** (three dots), hit **Import from File** and select the JSON file
  </Step>

  <Step title="Configure credentials">
    Set up your Crossmint API credentials in the workflow nodes
  </Step>

  <Step title="Update personal data">
    Replace placeholder values with your own:

    * Email addresses
    * Wallet addresses
    * Admin signer private keys
    * Product URLs or IDs
    * Delivery address
  </Step>

  <Step title="Test in Staging">
    Run the workflow in Staging environment first to verify everything works
  </Step>

  <Step title="Execute">
    Run the workflow and monitor the results
  </Step>
</Steps>

## Need More Help?

<CardGroup>
  <Card title="Ask the Expert GPT" icon="robot" href="https://chatgpt.com/g/g-68d13ccc81ac8191a0c3716ce980faff-n8n-crossmint-expert">
    Get AI-powered guidance on building workflows
  </Card>

  <Card title="Wallets Node" icon="wallet" href="/solutions/n8n/nodes/wallets">
    Learn about all wallet operations and features
  </Card>

  <Card title="Checkout Node" icon="credit-card" href="/solutions/n8n/nodes/checkout">
    Automate purchases from Amazon and Shopify
  </Card>

  <Card title="View All Examples" icon="github" href="https://github.com/crossmint/n8n-nodes-crossmint/tree/main/workflows-examples">
    Browse all workflow examples on GitHub
  </Card>
</CardGroup>


# Checkout Node
Source: https://docs.crossmint.com/solutions/n8n/nodes/checkout

Automate purchases from Amazon and Shopify using digital money

The Crossmint Checkout node enables you to automate purchasing physical products using digital money like USDC. This is a two-step process: first create an order, then pay for it.

## Operations

### Create Order

Creates a purchase order for a product from Amazon or Shopify.

**Parameters:**

* **Platform** — `amazon` or `shopify`
* **Product Identifier** — Product URL or ASIN/ID (e.g., Amazon URL or `B01DFSADS2`)
* **Recipient Email** — For order confirmation
* **Recipient Name** — Full name for shipping
* **Address Line 1/2** — Street address
* **City** — City name
* **State** — State/province (optional)
* **Postal Code** — ZIP/postal code
* **Country** — Country code
* **Environment** — Staging or Production
* **Payment Method** — Blockchain network (e.g., `solana`)
* **Payment Currency** — Token to use (e.g., `usdc`)
* **Payer Address** — Wallet address that will pay for the order

**Response:**

The response includes a `serializedTransaction` that you'll need for the next step.

### Pay Order

Completes the payment for a previously created order using a wallet's private key.

**Parameters:**

* **Serialized Transaction** — From the Create Order response
* **Payment Chain** — Network for payment (e.g., `solana`)
* **Payer Wallet Address** — Address of the paying wallet
* **Private Key** — Private key to authorize the payment

**Response:**

Returns the payment status and transaction details.

## Complete Workflow Example

Here's a typical workflow for purchasing an item:

<Steps>
  <Step title="Create Order">
    Use the **Create Order** operation with:

    * Product URL or ID
    * Shipping details
    * Payment method and payer wallet
  </Step>

  <Step title="Extract Transaction">
    From the Create Order response, extract the `serializedTransaction` field
  </Step>

  <Step title="Pay Order">
    Use the **Pay Order** operation with:

    * The serialized transaction
    * The payer wallet's private key
    * Payment chain information
  </Step>

  <Step title="Verify Completion">
    Check the response to confirm the payment was successful
  </Step>
</Steps>

## Supported Platforms

### Amazon

Purchase any product available on Amazon using cryptocurrency.

**Product Identifier Formats:**

* Full Amazon URL: `https://www.amazon.com/dp/B08N5WRWNW`
* ASIN only: `B08N5WRWNW`

### Shopify

Purchase products from Shopify-powered stores.

**Product Identifier Formats:**

* Product URL from the Shopify store

## Payment Methods

Currently supported:

* **Solana** — Pay with USDC or other SPL tokens on Solana

## Testing

<Callout type="info">
  Always test your checkout workflows in the **Staging** environment before moving to production. Use test USDC from the [Circle Faucet](https://faucet.circle.com/).
</Callout>

## Security Considerations

<Callout type="warning">
  <b>Private Key Security</b>

  The Pay Order operation requires a private key to sign transactions. Follow these security practices:

  1. Store private keys in n8n environment variables, never hardcode them
  2. Use different keys for staging vs production
  3. Only use keys with the minimum required balance
  4. Monitor wallet activity regularly
  5. Never share private keys or expose them in logs
</Callout>

## Example Use Cases

* **AI Shopping Assistants** — Build chatbots that can purchase items on behalf of users
* **Automated Reordering** — Set up workflows that automatically reorder supplies when inventory is low
* **Reward Systems** — Create systems that automatically purchase and ship rewards to users
* **Subscription Boxes** — Automate recurring purchases and deliveries

## Next Steps

<CardGroup>
  <Card title="Wallets Node" icon="wallet" href="/solutions/n8n/nodes/wallets">
    Learn about managing wallets for payments
  </Card>

  <Card title="Example Workflows" icon="diagram-project" href="/solutions/n8n/example-workflows">
    See the Checkout node in action with complete examples
  </Card>

  <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>


# 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="Checkout Node" icon="credit-card" href="/solutions/n8n/nodes/checkout">
    Automate purchases from Amazon and Shopify
  </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="Checkout Node" icon="credit-card" href="/solutions/n8n/nodes/checkout">
    Learn about the Checkout node for automated purchases
  </Card>

  <Card title="Example Workflows" icon="diagram-project" href="/solutions/n8n/example-workflows">
    See the Wallets node in action
  </Card>

  <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

Full-featured n8n integration for Crossmint Wallet and Checkout APIs

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

<img alt="n8n automated workflow example" />

<figcaption>Example n8n workflow demonstrating automated Amazon purchases powered by LLMs</figcaption>

## Available Crossmint Nodes in N8N

Crossmint n8n community package provides three powerful nodes:

* **Crossmint Wallets** — Manage blockchain wallets, check balances, and transfer tokens
* **Crossmint Checkout** — Automate purchases of physical products from Amazon and Shopify using digital money
* **Crossmint Checkout Trigger** — Create payment-gated webhook endpoints using the x402 protocol

## Example Use Cases

* **Payroll System** — Automate payments to employees and contractors worldwide
* **Agentic Payments** — Allow agents to purchase items on Amazon and Shopify
* **Automated Tipping** — Tip users on X (Twitter) automatically

## 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">login</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 Node">
    In the middle of the screen, click <b>Add first step</b>. In the search bar, type <b>Crossmint</b> to find the Crossmint nodes.<br /><br />
    For both <b>Crossmint Wallets</b> and <b>Crossmint Checkout</b> nodes, you need to click the <b>Install Node</b> button to add them to your workspace.
  </Step>
</Steps>

You now have access to two nodes: **Crossmint Wallets** and **Crossmint Checkout**. You can 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>
          <li><b>Crossmint Checkout</b></li>
        </ul>
      </li>

      <img alt="Crossmint node search" />

      <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="Example Workflows" icon="diagram-project" href="/solutions/n8n/example-workflows">
    Try ready-to-use workflow templates
  </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/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>

## Agents and Automation

<CardGroup>
  <Card title="Agentic Commerce" icon="robot" href="/solutions/ai-agents/introduction">
    Enable AI agents to purchase physical goods programmatically
  </Card>

  <Card title="n8n" icon="diagram-project" href="/solutions/n8n/overview">
    Create workflows to automate payments, money movement, and purchasing
  </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, 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, accepting both fiat and crypto payments

## 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 by accepting fiat or crypto for it
  </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 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

* Accept fiat or crypto payments 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="Setup 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 (not through your platform's payment flow), 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. Crossmint acts as the regulated party and handles all of this on your behalf — 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 type of entity (individual vs. business)
* The activity they will perform (receiving a payout vs. on-ramping fiat)
* The jurisdictions involved

You do not need to decide the KYC/KYB level yourself. The API tells you what is required and guides the verification flow.

### 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 '{
          "chain": "base-sepolia",
          "adminSigner": {
              "type": "evm-keypair",
              "address": "<your-recovery-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 '{
          "chain": "base-sepolia",
          "adminSigner": {
              "type": "evm-keypair",
              "address": "<your-recovery-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",
      recovery: { 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",
      recovery: { 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 = {
      "chain": "base-sepolia",
      "adminSigner": {
          "type": "evm-keypair",
          "address": "<your-recovery-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 = {
      "chain": "base-sepolia",
      "adminSigner": {
          "type": "evm-keypair",
          "address": "<your-recovery-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 will return an error with a specific reason code. Here are the potential compliance-related errors:

<AccordionGroup>
  <Accordion title="recipient_personal_data_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": {
            "reason": "recipient_personal_data_missing",
            "message": "Required personal data is missing to complete regulated transfer"
        }
    }
    ```
  </Accordion>

  <Accordion title="recipient_wallet_sanctioned" icon="shield-xmark">
    **Error Message:** "Recipient wallet address is sanctioned and can't receive assets"

    **Description:** The recipient's wallet address failed Elliptic sanctions screening. This indicates the address has been flagged in sanctions lists or is associated with prohibited activities.

    **Resolution:** The payout cannot proceed. The recipient's wallet address has been identified as high-risk and is blocked from receiving payouts.

    <Expandable title="How to test">
      In staging, you can trigger a sanctions 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": {
            "reason": "recipient_wallet_sanctioned",
            "message": "Recipient wallet address is sanctioned and can't receive assets"
        }
    }
    ```
  </Accordion>

  <Accordion title="recipient_person_sanctioned" 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": {
            "reason": "recipient_person_sanctioned",
            "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_type_unsupported" 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 `recipient_ownership_unverified` 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": {
            "reason": "recipient_type_unsupported",
            "message": "Regulated transfers can only be sent to Crossmint-managed wallets or external wallets linked to a Crossmint user."
        }
    }
    ```
  </Accordion>

  <Accordion title="recipient_ownership_unverified" 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 [Proof of Ownership](/onramp/guides/proof-of-ownership) for the full flow, including how to sign the challenge on EVM and Solana.

    ```jsonc theme={null}
    // Example error response
    {
        "error": {
            "reason": "recipient_ownership_unverified",
            "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 `recipient_personal_data_missing` errors.
  </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 and Elliptic
  </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 and Elliptic.
* **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": {
                  "adminSigner": {
                      "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",
          recovery: {
              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": {
              "adminSigner": {
                  "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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/architecture) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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 signers 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** is a cryptographic identity — such as a device key, passkey, server key, or external wallet — authorized to approve actions on the wallet's behalf.

Every Crossmint wallet organizes its signers into two distinct roles:

* **Signers** handle day-to-day operations: authorizing transactions, signing messages, and interacting with protocols. By default, Crossmint wallets use a **device signer** — a P256 key generated inside the user's device secure enclave (iOS Secure Enclave, Android Keystore, or a browser-based credential store). Signing adds zero latency and requires no network round-trip to Crossmint or any third-party server.
* **Recovery signers** are higher-friction signers used primarily for wallet recovery — for example, when a user switches to a new device and needs to enroll a new device key. Recovery signers use mechanisms like email OTP, SMS OTP, or server-held keys. They can also sign transactions as a fallback when no signer is available.

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.

<Info>
  Recovery signers can sign transactions — they are not limited to recovery operations. The SDK automatically falls back to the recovery signer when no signer is configured or available. However, for the best user experience, signers like device keys and passkeys are preferred for day-to-day use because recovery signers involve higher friction (for example, OTP verification).
</Info>

**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 key 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 additional signers based on email or phone number OTP. 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 [Signers](/wallets/concepts/signers) for the full signer type reference and [Recovery](/wallets/concepts/recovery) for how the recovery flow works.

## 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 server-side and AI agent wallets**, you get low-latency, deterministic signing from your own infrastructure. A server key 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.

<CardGroup>
  <Card title="Why Smart Contract Wallets?" icon="lightbulb" href="/wallets/why-smart-wallets">
    Learn why Crossmint chose smart contract wallets over MPC and off-chain key storage
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    Understand the signer types available for your wallets
  </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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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.

## 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 keys. In non-custodial models, recovery depends entirely on the user's recovery signer (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 signer (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.

| Signer          | Recovery signer           | 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 signer. The recovery signer matters too — recovery signers can sign 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 signer 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>


# Recovery
Source: https://docs.crossmint.com/wallets/concepts/recovery

How wallet recovery works in Crossmint — the separation of recovery and day-to-day signing, new device flows, and OTP verification

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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 signer and enroll a new device key.

## Why Recovery Signers Are Separate

In Crossmint's [dual-layer architecture](/wallets/architecture), every wallet has at least one recovery signer in addition to its day-to-day signer. These are separate because they solve different problems:

* **Signers** are optimized for speed and low friction. A device signer signs silently using the device's hardware security module — no OTP, no network call, no user interruption.
* **Recovery signers** are optimized for security at the cost of convenience. They use higher-friction authentication (email OTP, SMS OTP, or server-held keys) to ensure that only the rightful owner can restore access to a wallet.

If a single signer handled both roles, you would either sacrifice security (a frictionless signer that also controls recovery) or sacrifice UX (requiring OTP verification for every transaction).

## When Recovery Triggers

Recovery is needed when the wallet detects that no valid signer is available on the current device. The most common scenarios are:

* **New device** — the user opens your app on a phone or browser where no device signer has been created yet
* **Cleared storage** — the user cleared browser data or reinstalled the app, deleting the locally stored device key
* **Key mismatch** — the local device key does not match any signer registered onchain for the wallet (for example, after a key rotation)

The SDK detects these conditions automatically. When a wallet is loaded via `getWallet()`, it checks whether a valid device signer exists locally. If not, it sets an internal `needsRecovery` flag. You can check this flag explicitly using `wallet.needsRecovery()`.

## How Recovery Works

The recovery flow for device signers follows these steps:

1. **Detection** — the SDK loads the wallet and finds no valid local device key. `needsRecovery()` returns `true`.
2. **Authentication** — the recovery signer authenticates the user. For email or phone OTP signers, this means sending a one-time code and verifying the user's response. For server signers, the server authenticates using its secret.
3. **New key generation** — the SDK generates a new P256 keypair in the device's secure enclave (or browser credential store).
4. **Signer registration** — the SDK calls `addSigner()` to register the new device key onchain. This operation is authorized by the recovery signer — the smart contract verifies that the caller is an approved recovery signer before accepting the new key.
5. **Signer activation** — the new device signer becomes the active signer. `needsRecovery()` returns `false`.

<Info>
  Recovery runs automatically before every signing operation. If the SDK detects that recovery is needed, it triggers the recovery flow transparently via `recover()` before proceeding with the transaction. The user experiences a one-time OTP prompt (or no prompt at all, for server signers), after which all subsequent transactions on that device sign silently.
</Info>

### Preemptive Recovery

While recovery runs automatically when needed, you can also trigger it explicitly — for example, on app startup — to avoid interrupting the user's first transaction with an OTP prompt:

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

const { wallet } = useWallet();

if (wallet?.needsRecovery()) {
  await wallet.recover();
}
```

This is optional. If you do not call `recover()` explicitly, the SDK calls it automatically before the first signing operation.

## The OTP Flow

For wallets using email or phone OTP as the recovery signer, the recovery authentication flow works as follows:

1. The SDK requests an OTP to be sent to the user's email address or phone number.
2. The user receives the code and enters it in your application.
3. The SDK verifies the code and uses the authenticated recovery signer to register the new device key.

In React applications, Crossmint provides built-in OTP dialog components that handle the UI automatically.

## Recovery and Custody

Recovery is enforced **onchain** by the wallet's smart contract. Crossmint's backend does not have the ability to add signers, transfer assets, or bypass the recovery signer — all authorization logic lives in the smart contract. This means:

* In **non-custodial** configurations, only the user (via their recovery signer) can authorize new device keys.
* In **custodial** configurations using a server signer for recovery, the organization holding the server secret controls recovery.

See [Custody Models](/wallets/concepts/custody-models) for how signer choices affect custody classification.

## See Also

<CardGroup>
  <Card title="Wallet Recovery Guide" icon="rotate" href="/wallets/guides/signers/wallet-recovery">
    Step-by-step guide to recovering a wallet on a new device
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    Understanding the different signer types and when to use each one
  </Card>

  <Card title="Custody Models" icon="shield-halved" href="/wallets/concepts/custody-models">
    How signer and recovery choices map to custody architectures
  </Card>
</CardGroup>


# Signers
Source: https://docs.crossmint.com/wallets/concepts/signers

Understanding the different signer types in Crossmint wallets and when to use each one

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

A **signer** is a cryptographic identity authorized to approve actions on a Crossmint wallet. Signers are the control layer of the [dual-layer architecture](/wallets/architecture#dual-layer-architecture) — they determine who can authorize transactions, add new signers, or recover a wallet.

Every wallet has at least one signer, and most wallets have two: one for day-to-day operations and one for recovery.

## Signers and Recovery Signers

Crossmint wallets separate signers into two roles:

* **Signers** handle routine actions — signing transactions, approving token transfers, and interacting with protocols. They are optimized for low friction. The default signer for client-side wallets is the **device signer**, which uses the device's hardware security module to sign silently or with an optional biometric prompt.
* **Recovery signers** serve a different purpose. They are primarily used for wallet recovery (for example, enrolling a new device key after switching phones) and for adding new signers to a wallet. Recovery signers use higher-friction authentication — email OTP, SMS OTP, or server-held keys.

<Info>
  Recovery signers can also sign transactions as a fallback. When no signer is available or configured, the SDK automatically falls back to the recovery signer for transaction signing. This is useful for server-side wallets where the recovery signer may be the only signer configured.
</Info>

This separation exists because day-to-day signing and wallet recovery have fundamentally different security requirements. A signer should be fast and invisible — a user should not need to enter a one-time code every time they approve a transaction. A recovery signer, on the other hand, should be harder to use, because it controls access to the wallet itself.

## Signer Types

Crossmint supports eight signer types. Most can serve as either a signer or recovery signer depending on how they are configured — the device signer is the exception, since it can only be used as an operational signer, never for recovery. See the constraints noted under each type below.

### Device Signer

The device signer generates a P256 keypair inside the device's secure enclave (iOS Secure Enclave, Android Keystore) or in a browser-based credential store. The private key never leaves the hardware security boundary.

Key characteristics:

* **Default for client-side wallets** — automatically created when a wallet is initialized on a device, with no explicit configuration needed
* **Per-device** — each device gets its own signer. Device signers are not synced or portable across devices
* **Zero friction** — signs silently or with an optional biometric prompt. No OTP, no network call
* **Not a recovery signer** — device signers cannot be used as recovery signers

When a user switches to a new device, they use their recovery signer to authenticate and enroll a new device key on the new device. See [Recovery](/wallets/concepts/recovery) for details on this flow.

### 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 via the platform's passkey provider (iCloud Keychain, Google Password Manager, etc.).

Key characteristics:

* **Cross-device** — unlike device signers, passkeys can sync across devices within the same platform ecosystem
* **EVM only** — passkey signers are currently available only on EVM chains
* **Biometric or PIN authentication** — each signing operation requires user interaction (fingerprint, face scan, or device PIN)
* **Can be signer or recovery** — passkeys work in either role

If a wallet has multiple passkey signers, you must specify which one to use by providing its `id`. If only one passkey is registered, it is selected automatically.

### Server Signer

A server signer is backed by a secret held in your own infrastructure. The secret deterministically derives keypairs grouped by chain type, meaning the same secret always produces the same signer address for all EVM chains within a given project and environment — and a separate, distinct address for Solana and for Stellar.

Key characteristics:

* **Server-side only** — designed for backend applications, treasury wallets, and AI agents where no user device is involved
* **Zero latency** — signing happens entirely in-process with no external calls
* **Deterministic** — the derived address is a function of the secret, chain type (EVM/Solana/Stellar), project ID, and environment. A single secret produces one address shared across all EVM networks
* **Can be signer or recovery** — server signers work in either role

<Info>
  For server-only wallets, refer to the [server-side quickstart](/wallets/quickstarts/nodejs) for the current recommended configuration.
</Info>

### Email OTP Signer

The email OTP signer authenticates by sending a one-time code to the user's email address. The user enters the code to authorize the operation.

Key characteristics:

* **Can be signer or recovery** — email signers can be configured as recovery signers at wallet creation time, or added as operational signers via `addSigner()`
* **Multiple per wallet** — a wallet can have more than one email signer
* **Familiar UX** — leverages an authentication pattern that most users already understand

### SMS / Phone OTP Signer

The phone OTP signer works identically to the email OTP signer, but sends the one-time code via SMS instead of email.

Key characteristics:

* **Can be signer or recovery** — phone signers can be configured as recovery signers at wallet creation time, or added as operational signers via `addSigner()`
* **Multiple per wallet** — a wallet can have more than one phone signer

### External Wallet Signer

The external wallet signer delegates signing to a wallet the user already controls — such as MetaMask, Phantom, or any wallet that supports the relevant chain's signing standard.

Key characteristics:

* **Bring-your-own-wallet** — the user provides their existing wallet address and a signing callback
* **Can be signer or recovery** — external wallets work in either role
* **Chain-specific signing** — the `onSign` callback receives chain-appropriate payloads (hex string for EVM, `VersionedTransaction` for Solana, string payload for Stellar)

### Cloud KMS Signer

A Cloud KMS signer uses a non-extractable key stored in a cloud key management service — AWS KMS, Azure Key Vault, or GCP Cloud HSM. The private key never leaves the KMS boundary; all signing operations are performed inside the cloud provider's hardware security module.

Key characteristics:

* **Enterprise-grade security** — non-extractable keys with full cloud IAM controls, audit logging, and optional multi-party approval
* **High throughput** — supports up to \~1,000 signing operations per second per key
* **Can be signer or recovery** — Cloud KMS keys work in either role. As a recovery signer, they provide a secure, auditable path for key rotation and disaster recovery
* **Server-side only** — designed for company wallets, treasury operations, and custodial architectures where signing is controlled by your infrastructure

Cloud KMS signers are best suited for organizations that already use cloud KMS infrastructure and want to bring their existing key management practices to Crossmint wallets.

<Card title="Cloud KMS Implementation Guide" icon="arrow-right" href="/wallets/guides/signers/cloud-kms" />

### API Key Signer (Deprecated)

<Warning>
  The API key signer is deprecated and will be removed in a future release. Use a **server signer** instead for server-side signing.
</Warning>

The API key signer uses the Crossmint API key for authentication. It exists for backward compatibility with pre-V1 integrations.

## 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 OTP recovery signer 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 signer. This allows you to rotate the primary key without losing access to the wallet.

### 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                     | Signer                     | Recovery signer                            | Custody model |
| ---------------------------- | -------------------------- | ------------------------------------------ | ------------- |
| Consumer app (non-custodial) | Device signer (default)    | Email or phone OTP                         | 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 OTP                         | 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 any signers and recovery signers 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 can be removed. The wallet's recovery signer cannot be removed.
</Note>

The wallet's recovery signer must approve the removal. In the SDK this is handled automatically; 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 recovery signer by default.

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" icon="rotate" href="/wallets/concepts/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/why-smart-wallets) 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 (`owner: "USER"`)                  | 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 payment flows 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 payment 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 Extensions
Source: https://docs.crossmint.com/wallets/concepts/wallet-extensions

Overview of wallet plugin capabilities including yield generation, token swapping, and credit card issuance

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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 [Credit Cards guide](/wallets/guides/wallet-extensions/credit-cards) for integration details.

## 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>


# 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/bring-your-own-auth) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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",
                                  recovery: { 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",
                                recovery: { 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.sdk.Crossmint
        import com.crossmint.kotlin.auth.CrossmintAuthManager
        import com.crossmint.kotlin.auth.models.AuthToken

        // In Application.onCreate:
        Crossmint.shared(apiKey = "YOUR_CROSSMINT_API_KEY", appContext = this)

        // In your composable or ViewModel:
        val sdk = LocalCrossmintSDK.current
        val authManager = sdk.authManager as CrossmintAuthManager

        // Pass the JWT from your auth provider
        authManager.authenticateWithToken(
            AuthToken(
                jwt = "YOUR_PROVIDER_JWT",
                refreshToken = "YOUR_REFRESH_TOKEN",
                userEmail = "user@example.com"
            )
        )
        ```
      </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

        val wallet = sdk.crossmintWallets.getWallet(chain = EVMChain.BaseSepolia)
            .getOrNull()
            ?: sdk.crossmintWallets.createWallet(
                chain = EVMChain.BaseSepolia,
                recovery = SignerType.Email("user@example.com")
            ).getOrThrow()

        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 CrossmintAuth
        import CrossmintClient

        // Initialize the auth manager
        let authManager = try CrossmintAuthManager(apiKey: crossmintApiKey)

        // Pass the JWT from your auth provider
        await authManager.setJWT("YOUR_PROVIDER_JWT")

        // Initialize the SDK with the auth manager
        let sdk = CrossmintSDK.shared(
            apiKey: crossmintApiKey,
            authManager: authManager
        )
        ```
      </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,
            recovery: EVMSigners.email("user@example.com")
        ) {
            wallet = existing
        } else {
            wallet = try await sdk.crossmintWallets.createWallet(
                chain: EVMChain.baseSepolia,
                recovery: 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/check-balances) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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.Crossmint
        import com.crossmint.kotlin.types.EVMChain

        val sdk = Crossmint.instance
        val wallet = sdk.crossmintWallets.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

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        )

        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="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

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        )

        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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/create-wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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 signer** — 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.

<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",
        recovery: {
            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",
        recovery: {
            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",
        recovery: {
            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.Crossmint
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType

    val sdk = Crossmint.instance
    val result = sdk.crossmintWallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recovery = SignerType.Email("user@example.com")
    )
    val wallet = result.getOrThrow()
    println("Wallet address: ${wallet.address}")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared(
        apiKey: crossmintApiKey,
        authManager: crossmintAuthManager
    )

    let wallet = try await sdk.crossmintWallets.createWallet(
        chain: EVMChain.baseSepolia,
        recovery: 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": {
                  "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>

<Note>
  The REST API uses `adminSigner` (recovery role) and `delegatedSigners` (operational signers). These map to `recovery` and `signers` in the SDK.
</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.Crossmint
    import com.crossmint.kotlin.types.EVMChain

    val sdk = Crossmint.instance
    val result = sdk.crossmintWallets.getWallet(chain = EVMChain.BaseSepolia)
    val wallet = result.getOrThrow()
    println("Wallet address: ${wallet.address}")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared(
        apiKey: crossmintApiKey,
        authManager: crossmintAuthManager
    )

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia,
        recovery: 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;

    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",
                recovery: {
                    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",
                recovery: {
                    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",
                recovery: {
                    type: "email",
                    email: "user@example.com",
                },
            });
        } else {
            throw error;
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.Crossmint
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType

    val sdk = Crossmint.instance
    val wallet = sdk.crossmintWallets.getWallet(chain = EVMChain.BaseSepolia)
        .getOrNull()
        ?: sdk.crossmintWallets.createWallet(
            chain = EVMChain.BaseSepolia,
            recovery = SignerType.Email("user@example.com")
        ).getOrThrow()
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared(
        apiKey: crossmintApiKey,
        authManager: crossmintAuthManager
    )

    let wallet: EVMWallet
    if let existing = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia,
        recovery: EVMSigners.email("user@example.com")
    ) {
        wallet = existing
    } else {
        wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.baseSepolia,
            recovery: 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/export-private-key) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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/signers/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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/get-staging-tokens) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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 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.Crossmint
    import com.crossmint.kotlin.types.EVMChain

    val sdk = Crossmint.instance
    val wallet = sdk.crossmintWallets.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

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia,
        recovery: EVMSigners.email("user@example.com")
    )

    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.

By default, gas sponsorship is **enabled** for all wallets without writing any code.

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://staging.crossmint.com/console">Crossmint Console</a>

## Enable or Disable Gas Sponsorship

You can disable or re-enable gas sponsorship in the Console.

<Steps>
  <Step title="Navigate to Wallets Settings">
    Open the <a href="https://staging.crossmint.com/console">Crossmint Console</a> and go to **Wallets → Settings**.
  </Step>

  <Step title="Toggle gas sponsorship">
    Use the toggle to enable or disable gas sponsorship for your project.

    <img alt="Gas Sponsorship Settings" />
  </Step>
</Steps>

<Note>
  When using Solana as a chain, if you disable sponsorship, you can configure whether users pay gas in SOL or USDC.

  <img alt="Gas Sponsorship Solana Options" />
</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

* **Start with sponsorship enabled**: Gas sponsorship significantly improves user experience and conversion rates, especially for users new to blockchain
* **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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/list-transfers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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 signer                  | Recovery signers are high-friction (OTP-based). They can also sign transactions as a fallback when no operational signer is available.                                                                                                                      |
| `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.recovery`         | The `signer` field in `createOnLogin` is now `recovery`.                                                                                                                                                                                                    |
| `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 `recovery`, and `delegatedSigners` is now `signers`.

<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",
      recovery: { 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",
              recovery: { 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 signer.

### 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",
      recovery: { 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 named `recovery`.

<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,
          recovery: 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 signer.

### 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 named `recovery`.

<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,
              recovery = 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 signer.

### 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 signer), 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}`,
              recovery: { type: "email", email: USER_EMAIL },
          });
      }
  }
  ```
</CodeGroup>

### 3. Update signer configuration

The old `signer` field (admin signer) is now `recovery`, and `delegatedSigners` is now `signers`.

<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}`,
      recovery: { 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}`,
      recovery: { 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 '{
      "type": "evm-smart-wallet",
      "config": {
        "adminSigner": {
          "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` → `recovery`
* [ ] **(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` → `recovery`, `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>


# 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/send-transaction-evm) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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);

    // Replace with the target contract address
    const TARGET_CONTRACT = "0x...";
    // Replace with the calldata for your contract interaction
    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!;
    // Replace with your wallet address
    const WALLET_ADDRESS = "0x...";
    // Replace with the target contract address
    const TARGET_CONTRACT = "0x...";
    // Replace with the calldata for your contract interaction
    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);

    // Replace with the target contract address
    const TARGET_CONTRACT = "0x...";
    // Replace with the calldata for your contract interaction
    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

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: .baseSepolia
    )

    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/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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/send-transaction-solana) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/send-transaction-stellar) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: StellarChain.stellar,
        recovery: StellarSigners.email("user@example.com")
    )

    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.onChainTransactionId ?? "")")
    ```

    ### 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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/sign-message-evm) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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.Crossmint
        import com.crossmint.kotlin.types.EVMChain

        val sdk = Crossmint.instance
        val wallet = sdk.crossmintWallets.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

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        )

        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` as the recovery signer (admin signer) you can skip the following steps.
            </Note>

            Sign the approval message field returned in the response inside `signature.approvals` using the signer.
          </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.Crossmint
        import com.crossmint.kotlin.types.EVMChain

        val sdk = Crossmint.instance
        val wallet = sdk.crossmintWallets.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

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        )

        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` as the recovery signer (admin signer) you can skip the following steps.
            </Note>

            Sign the approval message field returned in the response inside `signature.approvals` using the signer.
          </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.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

Use `addSigner()` to register additional signers on an existing wallet. The wallet's recovery signer must approve the operation — the SDK handles this automatically.

## Prerequisites

* An existing wallet with a recovery signer 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 signer to approve the operation
3. After approval, restores the previously active signer

For client-side wallets with an email or phone recovery signer, the user is prompted with an OTP to approve adding the new signer. For server signer recovery, approval happens automatically.

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 **EVM-only**. They are not supported on Solana or Stellar.
</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="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. (The EVM-only restriction above
    applies to all SDKs — passkey signers rely on WebAuthn, which is not
    supported on Solana or Stellar.)
  </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>
</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.

        <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 signer, then submit the approval. For EVM wallets, use the [approve signature](/api-reference/wallets/approve-signature) endpoint. For Solana and Stellar, use 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

### Operational Signers

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 only             | 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; can also be configured as recovery signer |
| Phone           | Yes                       | All                  | OTP-based; can also be configured as recovery signer |

### Recovery Signers

Recovery signers approve high-privilege operations (adding new signers, recovery). Access the recovery signer via `wallet.recovery`. See [Configure Wallet Recovery](/wallets/guides/signers/configure-recovery).

| Signer Type | Chains               | Notes                                                                                                                              |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Email       | All                  | OTP-based approval                                                                                                                 |
| Phone       | All                  | OTP-based approval                                                                                                                 |
| Server      | EVM, Solana, Stellar | Automatic approval (no OTP); see [Configure Wallet Recovery](/wallets/guides/signers/configure-recovery#server-signer-as-recovery) |

## 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/signers/configure-recovery">
    Set up recovery signers 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/signers#cloud-kms) in the Wallet Signers guide. 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 signer. The recovery signer 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",
        recovery: {
            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 signer. The recovery signer 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",
        recovery: {
            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>


# Configure Wallet Recovery
Source: https://docs.crossmint.com/wallets/guides/signers/configure-recovery

Set up a recovery signer so users can regain wallet access from a new device.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

A recovery signer lets users regain access to their wallet when their primary (device) signer is no longer available — for example, when they switch to a new phone or clear their browser data. The recovery signer authorizes the enrollment of a new device signer on the new device.

Recovery signers are configured at **wallet creation time**. You can choose from email OTP, SMS OTP, or a server signer depending on your application's needs.

<Note>
  Recovery signers can also sign transactions when needed — they are not limited to recovery only. However, they involve higher friction (OTP verification or server-side signing), so they are best reserved for recovery flows and as a fallback.
</Note>

## 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

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",
                            recovery: { 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",
        recovery: {
            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",
            recovery: {
                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",
                            recovery: { type: "email" },
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </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",
              "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 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",
          "config": {
              "adminSigner": {
                  "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>

    <Note>
      The REST API uses the legacy field name `adminSigner` for the recovery signer. The SDK uses `recovery`.
    </Note>
  </Tab>
</Tabs>

## SMS OTP Recovery

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.

<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",
                            recovery: {
                                type: "phone",
                                phone: "+1234567890",
                            },
                        }}
                    >
                        {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",
        recovery: {
            type: "phone",
            phone: "+1234567890", // E.164 format required
        },
    });
    ```
  </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",
            recovery: {
                type: "phone",
                phone: "+12223334444", // E.164 format required
            },
        });
    } 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",
                            recovery: {
                                type: "phone",
                                phone: "+1234567890",
                            },
                        }}
                    >
                        {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: 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",
              "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 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",
          "config": {
              "adminSigner": {
                  "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 Signer as Recovery

Use a server signer as the recovery signer when you want your backend to manage recovery without user-facing OTP flows. This is common for AI agents, backend automation, and hybrid architectures where the server creates wallets that clients later use.

```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",
    recovery: {
        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).

## 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:
   * **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 signer 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             |

## 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="Add Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Add passkeys or external wallets to an existing wallet
  </Card>
</CardGroup>


# Device Signer
Source: https://docs.crossmint.com/wallets/guides/signers/device-signer

How device signers work — hardware-backed P256 keypairs for frictionless transaction signing.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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",
                            recovery: { 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",
        recovery: { 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",
                            recovery: { 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', '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 signer (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/signers/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 signer, 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 signer)
    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",
      recovery: {
          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:
  #   - "adminSigner" instead of "recovery"
  #   - "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": {
              "adminSigner": {
                  "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:
  #   - "adminSigner" instead of "recovery"
  #   - "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": {
          "adminSigner": {
              "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",
                                recovery: { 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",
                                recovery: { 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 signer (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/signers/configure-recovery">
    Explore other recovery signer 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.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/signers/external-wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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",
                            recovery: { 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",
        recovery: { 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",
        recovery: { 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/signers/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 signer

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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. The recovery signer is accessed separately via `wallet.recovery`. 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');

    // Recovery 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 signer
      console.log("Recovery:", data.config?.adminSigner);

      // 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 signer
      print("Recovery:", data.get("config", {}).get("adminSigner"))

      # 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 Signer

The recovery signer is separate from the operational signers returned by `wallet.signers()`. Access it directly:

```typescript theme={null}
const recovery = wallet.recovery;
console.log("Recovery type:", recovery.type);
```

## 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 `recovery` and `signers` terminology. When using the REST API directly, the corresponding fields are `adminSigner` (recovery) 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 the recovery signer
    * **`failed`** — Registration failed
  </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/signers/configure-recovery">
    Set up recovery signers 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.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/signers/passkey) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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.

<Note>
  Passkey signers are **EVM only**. They are not supported on Solana or Stellar.
</Note>

## 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",
                            recovery: { 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",
        recovery: { type: "email", email: "user@example.com" },
        signers: [{ type: "passkey" }],
    });
    ```

    Each transaction triggers a biometric authentication prompt.
  </Tab>
</Tabs>

## Adding a Passkey to an Existing Wallet

If the wallet already exists with a different signer, you can add a passkey via `wallet.addSigner({ type: "passkey" })`. 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/signers/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>


# 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 a signer from an existing wallet. This revokes the signer's ability to perform day-to-day operations on behalf of the wallet. The wallet's recovery signer must approve the operation — the SDK handles this automatically.

Signer removal is supported on **EVM**, **Solana**, and **Stellar**. For more context on signer roles and removal, see [Wallet 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 recovery signer.
  </Tab>

  <Tab title="REST">
    When using the REST API, removing signers must be approved by the wallet's recovery signer. 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' \
              --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';

          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"

          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';

          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' \
              --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"

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.delete(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        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 signer (admin signer).
      </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/signers/configure-recovery">
    Set up recovery signers 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 signer. 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 signer**: The recovery signer 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 signer 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 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 signer.
      </Step>

      <Step title="Sign the approval message with the recovery signer">
        Sign the message field returned under the signature's `approvals` using the wallet's recovery signer.
      </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. The signer becomes active once the signature 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 signer">
        The response includes a `transaction` object. Sign the transaction returned under `transaction.approvals` with the wallet's recovery signer.
      </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 signer">
        Sign the transaction returned under `transaction.approvals` with the wallet's recovery signer.
      </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 signer authorizes the wallet creation.

<Note>
  The REST API uses `adminSigner` and `delegatedSigners` as field names. These map to `recovery` 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": {
            "adminSigner": {
                "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": {
            "adminSigner": {
                "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": {
            "adminSigner": {
                "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/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/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",
            recovery: {
                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.


# Recover a Wallet
Source: https://docs.crossmint.com/wallets/guides/signers/wallet-recovery

Regain access to a wallet when your operational signer is lost — use the recovery signer 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 the wallet's **recovery signer** to regain control. The recovery signer is a separate, higher-privilege signer 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 signer**, both on the client side. The same principles apply to other signer and recovery combinations.

<Note>
  This guide assumes you are using **Wallets SDK V1**. If you are on the previous version,
  see the [previous version docs](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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, the recovery signer lets you authorize a new operational signer without needing the original one.

## Prerequisites

* A wallet that was created with a recovery signer (email, phone, or server). If your wallet was not created with a recovery signer, this guide does not apply — see [Managed Support Center Recovery](#managed-support-center) below for enterprise options. To configure a recovery signer, see [Configure Wallet Recovery](/wallets/guides/signers/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 the recovery signer (for OTP-based recovery)

<Warning>
  If your wallet has a **server signer** as the recovery signer and you have also lost that secret, 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 It Works

The most common recovery scenario is switching to a new device. Here is what happens:

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 the recovery signer.
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 the recovery signer 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 **EVM-only** and require a browser that supports WebAuthn.
    </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. Use the recovery signer 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;

        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 signer with a phone recovery signer 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/signers/configure-recovery) for details on setting up phone OTP as the recovery signer.

## Alternative: Server-to-Server Recovery

If your wallet uses a **server signer** as both the operational and recovery signer (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 signer. 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 signer 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 and recovery server signers. 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 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>

## 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/signers/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>


# Spam Filters
Source: https://docs.crossmint.com/wallets/guides/spam-filters

Automatically block spam NFTs from your wallets

<Warning>
  Spam filters require an enterprise subscription. [Contact us](https://www.crossmint.com/contact/sales) to learn
  more.
</Warning>

Blocking spam NFTs from wallets is critical to delivering a good user experience and keeping your users safe, specially in low cost chains where spam is widespread.

Once spam filters are enabled for your project, the API to [get NFTs](/api-reference/wallets/get-nfts-from-wallet) from a wallet will flag spam NFTs, which you can use to hide potentially malicious assets.

You can access this information in two ways:

### Mode 1: Boolean

The API returns an `isSpam` attribute with values `true` or `false` based on Crossmint's default rules.

<Accordion title="See sample response">
  ```
  {
      "chain":"polygon",
      "contractAddress":"0xC5F45D4B5Be198A430b39D194cbB32132BE2cfec",
      "tokenId":"1",
      "metadata":{
      ...
      },
      "locator":"poly:0xC5F45D4B5Be198A430b39D194cbB32132BE2cfec:1",
      "tokenStandard":"erc-721",
      "isSpam":true
  }
  ```
</Accordion>

### Mode 2: Spam Score

The API returns a `spamScore` between 0-100 (100 = most likely to be spam), so you can adjust your tolerance threshold.

<Accordion title="See sample response">
  ```
  {
      "chain":"polygon",
      "contractAddress":"0xC5F45D4B5Be198A430b39D194cbB32132BE2cfec",
      "tokenId":"1",
      "metadata":{
      ...
      },
      "locator":"poly:0xC5F45D4B5Be198A430b39D194cbB32132BE2cfec:1",
      "tokenStandard":"erc-721",
      "spamScore":50 //This is a range of 0-100 
  }
  ```
</Accordion>


# Transfer Tokens
Source: https://docs.crossmint.com/wallets/guides/transfer-tokens

Transfer tokens between wallets using Crossmint's APIs

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/transfer-tokens) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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.Crossmint
    import com.crossmint.kotlin.types.EVMChain

    val sdk = Crossmint.instance
    val wallet = sdk.crossmintWallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

    val transaction = wallet.send(
        recipient = "RECIPIENT_WALLET_ADDRESS",
        tokenLocator = "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"
    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: .baseSepolia
    )

    let result = try await wallet.send(recipientAddress, "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, '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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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).

## 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",
          recovery: { 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": {
                  "adminSigner": {
                      "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": {
              "adminSigner": {
                  "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
    * The `recovery` signer 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/error-handling) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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",
    "simulationLink": "https://www.tdly.co/shared/simulation/e61be684-5359-48a6-9173-349cd44c6e6c"
  }
}
```

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",
    "simulationLink": "https://www.tdly.co/shared/simulation/18b810b5-33b6-4091-a3a1-d7318f73bbec"
  }
}
```

Troubleshooting:

* Review the simulation to understand the revert cause
* 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",
            recovery: { 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, 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, you can use Tenderly to inspect the details. Otherwise, you can use a block explorer to inspect the transaction.

### Tenderly

[Tenderly](https://tenderly.co) is an EVM transaction tracing software. For each transaction that is failed during simulation, Crossmint API includes a link to the Tenderly simulation.

### 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/wallet-extensions/bridge-lifi) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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

    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/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>


# 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

    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 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.types.SignerData
    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)

    val sdk = LocalCrossmintSDK.current
    val wallet = sdk.crossmintWallets
        .getOrCreateWallet(EVMChain.Base, SignerData.Email(SIGNER_EMAIL))
        .getOrThrow()

    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

    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 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.types.SignerData
    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)

    val sdk = LocalCrossmintSDK.current
    val wallet = sdk.crossmintWallets
        .getOrCreateWallet(EVMChain.Base, SignerData.Email(SIGNER_EMAIL))
        .getOrThrow()

    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/concepts/wallet-extensions">
    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>


# 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/guides/wallet-extensions/swap-jupiter) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

## 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>


# 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/concepts/wallet-extensions) 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 wallets for users, agents, or company operations

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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/architecture">
    Read **Architecture** to understand the dual-layer model, then **Custody Models** for compliance implications.
  </Card>

  <Card title="Ready to build?" icon="code" href="/wallets/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/concepts/signers">
    Explore **Signers** to pick the right operational and recovery signer types for your use case.
  </Card>
</CardGroup>

## Smart Contract Wallets with Modular Signers

Most wallet providers couple the private key and the wallet together. Crossmint takes a different approach: wallets are [smart contract wallets](/wallets/why-smart-wallets) with a [modular signer architecture](/wallets/concepts/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/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 funds.

<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/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/architecture)
* [Signers](/wallets/concepts/signers)
* [Create a wallet](/wallets/guides/create-wallet)
* [Transfer tokens](/wallets/guides/transfer-tokens)
* [Get balance](/wallets/guides/check-balances)
* [Webhooks](/wallets/guides/webhooks)
* [Glossary](/introduction/glossary)


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

## 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/quickstarts/kotlin) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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.0.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.0.1")
            implementation("com.crossmint:crossmint-compose:1.0.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.Crossmint

    val CROSSMINT_API_KEY = "ck_staging_your_key_here"

    class MyApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            Crossmint.shared(apiKey = CROSSMINT_API_KEY, appContext = this)
        }
    }
    ```

    Then wrap your top-level composable with `CrossmintNonCustodialSignerProvider`:

    ```kotlin theme={null}
    @Composable
    fun QuickstartApp() {
        CrossmintNonCustodialSignerProvider(sdk = Crossmint.instance) {
            // 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.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">
            ```kotlin theme={null}
            import com.crossmint.kotlin.auth.CrossmintAuthManager
            import com.crossmint.kotlin.compose.LocalCrossmintSDK

            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 error: result.error.message
                }
            }
            ```
          </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

            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 error: result.error.message
                }
            }
            ```
          </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

        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 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 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

    val sdk = LocalCrossmintSDK.current
    val authManager = sdk.authManager as CrossmintAuthManager
    val crossmintWallets = sdk.crossmintWallets

    val email = authManager.authState.value.email ?: return

    when (val result = crossmintWallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recovery = SignerType.Email(email)
    )) {
        is Result.Success -> {
            val wallet = result.value // Wallet is ready to use!
        }
        is Result.Failure -> {
            // Handle error: result.error.message
        }
    }
    ```

    <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}
    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 error: result.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)**

    ```kotlin theme={null}
    when (val result = wallet.fund(token = "usdxm", amount = 10, chain = "base-sepolia")) {
        is Result.Success -> { /* Funded! */ }
        is Result.Failure -> {
            // Handle error: result.error.message
        }
    }
    ```

    **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}
    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.Crossmint
    import com.crossmint.kotlin.compose.CrossmintNonCustodialSignerProvider
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import kotlinx.coroutines.launch

    @Composable
    fun QuickstartApp() {
        CrossmintNonCustodialSignerProvider(sdk = Crossmint.instance) {
            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.


# Node.js
Source: https://docs.crossmint.com/wallets/quickstarts/nodejs

Create and manage wallets from your backend in under 5 minutes

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/quickstarts/nodejs) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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",
        recovery: {
            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

## 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/quickstarts/react) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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",
                            recovery: { 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.

## 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version, see the [previous version of this page](/wallets/v0/quickstarts/react-native) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

<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",
                            recovery: { 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.

## 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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/quickstarts/restapi) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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": {
                      "adminSigner": {
                          "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: {
                      adminSigner: {
                          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": {
                  "adminSigner": {
                      "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.adminSigner`: The recovery signer for the wallet
          * `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": {
                  "adminSigner": {
                      "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": {
                      "adminSigner": {
                          "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: {
                      adminSigner: {
                          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": {
                  "adminSigner": {
                      "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": {
                  "adminSigner": {
                      "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": {
                      "adminSigner": {
                          "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: {
                      adminSigner: {
                          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": {
                  "adminSigner": {
                      "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": {
              "adminSigner": {
                  "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": {
            "adminSigner": {
                "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

<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

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/quickstarts/swift) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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>"
    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/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 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.errorMessage
            }
            ```
          </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.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 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 = crossmintAuthManager.email else {
            // User not authenticated — return to the auth step
            return
        }

        let wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.baseSepolia,
            recovery: EVMSigners.email(email)
        )

        // Wallet is ready to use!
        print("Wallet address: \(wallet.address)")
    } catch let error as WalletError {
        // Handle error: error.errorMessage
    }
    ```

    <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.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 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.txId)")
    } catch let error as TransactionError {
        switch error {
        case .userCancelled:
            // User cancelled the transaction
            break
        default:
            // Handle error: error.errorMessage
            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

## 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",
    "simulationLink": "https://www.tdly.co/shared/simulation/e61be684-5359-48a6-9173-349cd44c6e6c"
  }
}
```

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",
    "simulationLink": "https://www.tdly.co/shared/simulation/18b810b5-33b6-4091-a3a1-d7318f73bbec"
  }
}
```

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, you can use Tenderly to inspect the details. Otherwise, you can use a block explorer to inspect the transaction.

### Tenderly

[Tenderly](https://tenderly.co) is an EVM transaction tracing software. For each transaction that is failed during simulation, Crossmint API includes a link to the Tenderly simulation.

### 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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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` as the recovery signer (admin signer) you can skip the following steps.
        </Note>

        Sign the approval message field returned in the response inside `signature.approvals` using the signer.
      </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` as the recovery signer (admin signer) you can skip the following steps.
        </Note>

        Sign the approval message field returned in the response inside `signature.approvals` using the signer.
      </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-key) 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-key) 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 & Phone">
            [Email and phone](/wallets/guides/signers/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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.

        <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/concepts/wallet-extensions) 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/why-smart-wallets) 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>


# Why Smart Contract Wallets
Source: https://docs.crossmint.com/wallets/why-smart-wallets

Why Crossmint chose smart contract wallets as the foundation for its wallet infrastructure.

<Note>
  **This page has been updated for Wallets SDK V1.** If you are using the previous version,
  see the [previous version of this page](/wallets/v0/why-smart-wallets) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Note>

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/architecture">
    See how the dual-layer architecture works in practice.
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    Explore the signer types that plug into this architecture.
  </Card>
</CardGroup>