# Openfort Documentation

> Comprehensive tutorials on smart accounts, API integration, and wallet management.

import { HomePage } from "vocs/components";

<HomePage.Root>
  <HomePage.Logo />

  <div />

  <HomePage.Tagline>Make wallets our problem. Not yours</HomePage.Tagline>
  <HomePage.Description>Openfort is an open source alternative to wallet infrastructure solutions.<br />Supercharge your project with authentication, user management and payments.</HomePage.Description>

  <HomePage.Buttons className="mt-4">
    <HomePage.Button href="/overview" variant="accent" className="text-white!">Get started</HomePage.Button>
    <HomePage.Button href="https://github.com/openfort-xyz">GitHub</HomePage.Button>
  </HomePage.Buttons>
</HomePage.Root>


## Entity Addresses

A list of contract addresses deployed by Openfort.

### Paymaster

| Chains              | Address                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Mainnet Address** | [0x51032c841E823BB487C33c9f1773B18C8d0E5209](https://contractscan.xyz/contract/0x51032c841E823BB487C33c9f1773B18C8d0E5209) |
| **Testnet Address** | [0x3210deD2e50363eF645C4eA15339Bec8Ac88e0F5](https://contractscan.xyz/contract/0x3210deD2e50363eF645C4eA15339Bec8Ac88e0F5) |

### Factories

#### UpgradeableAccountFactory V6

| Chains              | Address                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Mainnet Address** | [0x2fcb244d49f712c38109ba0bfc21433a4dd4452d](https://contractscan.xyz/contract/0x2fcb244d49f712c38109ba0bfc21433a4dd4452d) |

#### UpgradeableAccountFactory V5

| Chains              | Address                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Mainnet Address** | [0x5a2ed3e47798123ae30477424731de2ae47cc158](https://contractscan.xyz/contract/0x5a2ed3e47798123ae30477424731de2ae47cc158) |
| **Testnet Address** | [0xcb71e008b9062bb7abd558816f8135ef2cab576f](https://contractscan.xyz/contract/0xcb71e008b9062bb7abd558816f8135ef2cab576f) |

### Implementation

#### UpgradeableAccountImplementation V5

| Chains              | Address                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Mainnet Address** | [0x6e4a235c5f72a1054abFeb24c7eE6b48AcDe90ab](https://contractscan.xyz/contract/0x6e4a235c5f72a1054abFeb24c7eE6b48AcDe90ab) |
| **Testnet Address** | [0xc8ebbdd2da25906b96c374c9b1757b1421e9f45a](https://contractscan.xyz/contract/0xc8ebbdd2da25906b96c374c9b1757b1421e9f45a) |

#### ERC6651AccountImplementation V1

| Chains              | Address                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Mainnet Address** | [0x528fe3cf9a857127eceb6df26ac7535839bfaef8](https://contractscan.xyz/contract/0x528fe3cf9a857127eceb6df26ac7535839bfaef8) |
| **Testnet Address** | [0x528fe3cf9a857127eceb6df26ac7535839bfaef8](https://contractscan.xyz/contract/0x528fe3cf9a857127eceb6df26ac7535839bfaef8) |

### Forward contract

| Chains              | Address                                    |
| ------------------- | ------------------------------------------ |
| **Mainnet Address** | 0xc82BbE41f2cF04e3a8efA18F7032BDD7f6d98a81 |
| **Testnet Address** | 0xc82BbE41f2cF04e3a8efA18F7032BDD7f6d98a81 |
| **Beam**            | 0xd04f98c88ce1054c90022ee34d566b9237a1203c |


## API Keys

### Livemode and testing

Every account is divided into two universes: one for *testnet*, and one for *mainnet*. All requests exist in one of those two universes, and objects in one universe cannot be manipulated by objects in the other. In **test mode**, transactions can only go to **testnet networks**.

### API keys

You'll need to authenticate your requests to access any of the endpoints in the Openfort API. API keys are used to authenticate these requests.

#### Project secret and publishable keys

All accounts have a total of four API keys by default—two for test mode and two for live mode:

1. **Test project secret key:** Use this key to authenticate requests on your server when in test mode. By default, you can use this key to perform any API request without restriction.
2. **Test project publishable key:** Use this key for testing purposes in your web or mobile app's client-side code.
3. **Live project secret key:** Use this key to authenticate requests on your server when in live mode. By default, you can use this key to perform any API request without restriction.
4. **Live project publishable key:** Use this key, when you're ready to launch your app, in your web or mobile app's client-side code.

#### Shield secret and publishable keys

All accounts have a total of three API keys by default for Shield functionality:

1. **Shield secret key:** Use this key to store the recovery share of your users on server.
2. **Shield publishable key:** Use this key, when you're ready to launch your app, in your web or mobile app's client-side code.
3. **Shield encryption share key:** Only used whenever you're using the [automatic recovery](/docs/products/embedded-wallet/javascript/signer/recovery) to encrypt the recovery share.

| Type        | Value               | When to use                                                                                                                                                                                                                                                                 |
| ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Secret      | `sk_test_ypc...YZp` | **On the server-side**: Must be secret and stored securely in your web or mobile app's server-side code (such as in an environment variable or credential management system) to call Openfort APIs. Don't expose this key on a website or embed it in a mobile application. |
| Publishable | `pk_test_ZXb...aWg` | **On the client-side**: Can be publicly-accessible in your web or mobile app's client-side code (such as `openfort-js`).                                                                                                                                                    |

### Reveal an API secret key in your dashboard

Openfort APIs use your secret key to authenticate requests from your server. To find your API secret key for test mode:

1. Open the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) page.
2. Under `API keys`, in the `Secret key` row, click `Reveal test key` and save the value.

### Regenerate API keys

:::warning
Regenerating an API key will invalidate the current key and generate a new one. This action cannot be undone. If you have set up webhooks or registered a Shield project with the key, you will need to update them with the new key.
:::

Openfort supports the ability to regenerate, delete and create API keys. You can do this at any time in the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) section of the dashboard.

* **Delete and regenerate API keys**:

![generate-delete-api-keys](https://blog-cms.openfort.io/uploads/regenerate_delete_api_keys_f6b94994b0.png)

* **Generate new API keys**: You can create multiple API keys when you're planning to generate a new one to avoid disruption to your integration.

![generate-api-keys](https://blog-cms.openfort.io/uploads/generate_api_keys_5807b195fa.png)

### Limit API keys interaction by IP

Openfort supports limiting the IPs that can interact with Openfort services using specific API keys.

To enable this, navigate to the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) section of the dashboard and press the three dots next to the **secret key**.

A new page will appear with an option `Whitelist IPs` like so:

![whitelist-ips](https://blog-cms.openfort.io/uploads/regenerate_delete_api_keys_f6b94994b0.png)

You can then add multiple IPs per single secret key.

If you try to make a request from an unauthorized IP, you will receive a `Forbidden` error like so:

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Access is limited for this address"
  }
}
```


## Supported Blockchains

You can find a list of the chains that Openfort currently supports below. Openfort is compatible with all EVM chains.

<div>
  Don't see a chain you're interested in below? Get in touch, we'll make it available within 12 hours.
</div>

| Blockchains         | Testnet     | Mainnet   |
| ------------------- | ----------- | --------- |
| **Ancient8**        | 28122024    | 888888888 |
| **Arbitrum Nova**   |             | 42170     |
| **Arbitrum One**    | 421614      | 42161     |
| **Avalanche**       | 43113       | 43114     |
| **B3**              | 1993        | 8333      |
| **Base**            | 84532       | 8453      |
| **Beam**            | 13337       | 4337      |
| **Berachain**       |             | 80094     |
| **BNB**             | 97          | 56        |
| **Degen Chain**     |             | 666666666 |
| **DOS Chain**       | 3939        | 7979      |
| **Gnosis**          | 10200       | 100       |
| **Immutable zkEVM** | 13473       |           |
| **Kroma**           | 2358        | 255       |
| **Linea**           | 59140       | 59144     |
| **Mantle**          | 5001        | 5000      |
| **Monad**           | 10143       |           |
| **Soneium**         | 1946        |           |
| **OpBNB**           | 5611        | 204       |
| **Optimism**        | 420         | 10        |
| **Saakuru**         | 247253      | 7225878   |
| **Sophon**          | 531050104   | 50104     |
| **Polygon POS**     | 80002       | 137       |
| **Xai Network**     | 37714555429 | 660279    |
| **Zora**            | 999999999   | 7777777   |
| **ZKsync**          | 300         | 324       |


## Configure allowed domains

To secure use of your client-side Openfort publishable key, we strongly recommend setting allowed domains for any application in production. This is a security best practice that prevents arbitrary applications from reusing your openfortpublishable key in their own site.

You should always restrict allowed domains for any production application. This step is not necessary for the publishable key you use in staging, development, or local environments.

To configure allowed domains for your app, go to the Openfort dashboard and select your production app from the dropdown in the left sidebar. Then, navigate to the Configuration > Security.

Under Allowed Origins, list the domains that will use your production publishable key.

### Allowed domains format

When listing allowed domains, please follow these guidelines:

* The protocol **`https` is required**.
* **Trailing paths** (e.g. `/path`) are **not supported**.
* **Wildcards (`*`) are only supported as a subdomain**, e.g. `*.domain.com`.\
  Wildcards like `*.com` or partial wildcards such as `*-something.domain.com` are **not supported**.
* **Localhost** (`http://localhost:port`) is supported, **but the port number must be specified**.\
  While supported, **we do not recommend listing `localhost`** as an allowed domain for production apps.
  If you must add it temporarily (e.g. for development), **remember to remove it afterward**.
* Many hosting providers treat `https://www.example.com` and `https://example.com` as equivalent.\
  If that's true for your app, **add both versions (with and without `www`)** as allowed origins in the dashboard.

Setting allowed domains restricts client-side access to your Openfort publishable key only. Openfort's REST API endpoints that you would query from your backend are gated by your app secret, which should never be exposed on a user's client.

### Supporting preview URLs

Many hosting providers (e.g. Vercel) support preview deployment URLs to make it easy to test changes, like:

#### Matches the pattern \*.netlify.app

Which anyone with a free Netlify account can deploy to
`deploy-preview-id--yoursitename.netlify.app`.

For security reasons, we do not allow whitelisting domains with a generic pattern that are commonly used for these preview deployments, such as:

* https\://*.netlify.app / https\://*.vercel.app
* https\://*-projectname.netlify.app / https\://*-projectname.vercel.app
* Any project can deploy to a domain that matches https\://*.netlify.app, https\://*.vercel.app, or similar. If you were to whitelist this domain for your production publishable key, any actor could set up any arbitrary deployment with your hosting provider and can use your production publishable key within their site.

If you'd like to secure your Openfort publishable key on preview deployment URLs, please check if your hosting provider allows you to map preview deployments to a stable subdomain that only you control, like:

#### Matches the pattern \_.yoursitename.netlify.app

Which only members of your Netlify account (or hosting provider) can deploy to
deploy-preview-42<b>.yoursitename.netlify.app</b>
This allows you to list [https://\_.yoursitename.netlify.app](https://_.yoursitename.netlify.app) under allowed domains, which arbitrary actors cannot deploy to. See instructions to set this up with Vercel or Netlify.

Allowed domains are primarily recommended for production applications. If your preview deployments use a development Openfort publishable key, feel free to leave Allowed Origins empty to support use of your publishable key in previews without the setup above.

App clients and allowed domains
Within an app client, you can override Allowed origins on your app while still sharing the same user base. To add a client, go to the Configuration > App settings page > Clients tab, and find the Add app client button. Create a client and add Allowed origins.

Allowed OAuth redirect URLs
Similar to allowed domains, you can configure allowed OAuth redirect URLs to restrict where users can be redirected after they log in with an external OAuth provider. This is a security best practice that prevents users from being redirected to malicious sites with their authentication token. To configure allowed OAuth redirect URLs, navigate to Configuration > App settings > Advanced on the dashboard. Add the OAuth providers are allowed to redirect to after authentication.

> The URL must be an exact match for the redirect URL; query params and trailing slashes will error.
> The URL must be at a domain listed in allowed domains.
> The protocol (https) is required.
> Wildcards (\*) are not supported.
> If no URLs are listed, users can be redirected to any URL.


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Backend wallets

Backend wallets serve as an internal account for games and developers to manage assets and flows. The accounts are EOAs (Externally Owned Account).

<div align="center">
  <img alt="dev-account-dashboard" src="https://blog-cms.openfort.io/uploads/dev_account_dashboard_f73e699b8b.png" width="80%" height="80%" />
</div>

There are [several use cases](/docs/products/server/wallet) for this:

* **Treasury Account**: Transferring assets on demand.
* **Minting Account**: Minting assets on demand.
* **Escrow Account**: Hold assets or tokens in an escrow between users and transferring them afterwards.

### Requisites

Developer account pay for gas using either:

* **Support [ERC-2771](https://eips.ethereum.org/EIPS/eip-2771) transactions**: The assets you want to escrow need to support [ERC-2771](https://eips.ethereum.org/EIPS/eip-2771) transactions (i.e. gasless).
* **Funding a backend wallet**: You need to fund your developer account with the chain's native token.

### Create a backend wallet

Head to the [backend wallet](https://dashboard.openfort.io/developers/wallets) page in your dashboard settings and click on `Add account`. By default, the backend wallets created with Openfort are custodial.

#### Dashboard

<div align="center">
  <img alt="addDevAccount" src="https://blog-cms.openfort.io/uploads/custodial_dev_account_7bf9f3a20a.png" width="50%" height="50%" />
</div>

#### API

##### Node.js

```ts server.ts    
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const settings = await openfort.settings.createDeveloperAccount({
  name: 'Minting Account',
})
```

##### curl

```bash command-line
curl https://api.openfort.io/v1/settings/developer_accounts \
  -u "$YOUR_SECRET_KEY:" \
  -d name= "Minting Account"
```

#### Verify wallet ownership

If you're looking to **sponsor gas with your native tokens** for smart accounts, it's important to verify your deposited funds with the paymaster.

Head to [backend wallets](https://dashboard.openfort.io/accounts) in your dashboard and click on `Add account`.

1. Click on "Advanced Options" to start the process.
2. Sign the explorer message.
3. Add the wallet address used to deposit native tokens.
4. Add the signed message.

<div align="center">
  <img alt="noncustodial-dev-account" src="https://blog-cms.openfort.io/uploads/noncustodial_dev_account_01a86b37fa.png" width="60%" height="60%" />
</div>

<VideoSnippet title="Backend Wallets Demo" src="lWpcJJOcaLs" />

#### Optional: Custom forwarder contract

By default you can use the supported forwarder contracts from Openfort if you need.

Alternatively, you can also use your forward contract in order to sponsor the transaction of your backend wallet. Go to your [Gas policy](https://dashboard.openfort.io/policies) section and create a policy by adding the address of your `Forwarder contract address`.


## Ecosystem dashboard configuration

:::note
Creating your own global wallet is an **enterprise feature**. To enable it, please [contact us](https://t.me/joalavedra).
:::

Use the **customization** page of the dashboard to configure your ecosystem's brand settings, including name, logo, accent color, and legal policies.

<div align="center">
  <img alt="whitelabel_dashboard" src="https://blog-cms.openfort.io/uploads/whitelabel_dashboard_ef523dc779.png" width="100%" height="100%" />
</div>

### Customization options

| Customization | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| Domain        | Choose where to host your dashboard                               |
| Name          | Ecosystem name as you'd like to present it to users               |
| Logo          | Ecosystem logo                                                    |
| Brand color   | Accent color for your ecosystem                                   |
| Legal         | Used to set your own terms & conditions, and your privacy policy. |
| SDK links     | Client SDKs                                                       |
| Example links | Template examples using the ecosystem SDKs                        |


## Using a third-party auth provider

Openfort's signer solution enables the user onboarding by integrating with established backend solutions and authentication providers that support JWT-based authentication. This strategy provides a trusted, scalable, and versatile framework that supports an extensive range of authentication options.

### Third-party auth platforms

With this approach, Openfort is in charge of creating **embedded signers** on the and follow the necessary security steps to make sure the smart wallet created remains non custodial.

* **[PlayFab](/docs/configuration/external-auth/playfab)**
* **[Firebase](/docs/configuration/external-auth/firebase)**
* **[Accelbyte](/docs/configuration/external-auth/accelbyte)**
* **[Lootlocker](/docs/configuration/external-auth/lootlocker)**
* **[Supabase](/docs/configuration/external-auth/supabase)**

### Custom Auth Methods

We offer two options to setup embedded signers with custom auth, one that is based on the OIDC ([Open ID Connect](https://openid.net/developers/how-connect-works/)) standard, and a generic option that lets you bring your own auth server.

* **[Custom OIDC Token](/docs/configuration/custom-auth/oidc-token)**
* **[Custom Auth Token](/docs/configuration/custom-auth/auth-token)**


## FAQs

#### Can players use ERC-20 tokens to pay for gas fees?

Yes, you can sponsor fully or partially with the network token or ERC-20.

#### Do users need to fund the newly created accounts?

You don't need to. With Openfort you can use policies to sponsor gas fees on behalf of your users.

#### How do I pay for the sponsored gas fees?

Openfort handles all the gas payments for you when using policies. While everything is free on `Testnets`, on `Mainnets` you'll need to top up your account.

#### What smart contracts can I interact with?

Yes, you're free to use any smart contracts you wish. You will need add contracts using the assets page in your dashboard.

#### Is Openfort ERC-4337 compatible?

Yes, Openfort is compatible with Account Abstraction (ERC-4337) among other standards and follows best practices and implementations across other ethereum standards.

#### What blockchains do you support?

Checkout the comprehensive list of [supported chains](/docs/configuration/chains).

#### Can users have the same smart account address on all EVM chains?

Yes, users can have the same address across all EVM chains because the addresses are deterministic. Each chain will have separate smart account.

#### Has Openfort been audited?

The Smart Account implementation has been [audited by CertiK](https://drive.google.com/drive/u/0/folders/1aoPgJD_oz1qagWflnO91ASlQo-2upjRL) and the embedded wallet is [audited by Cure+53](https://drive.google.com/drive/u/0/folders/1aoPgJD_oz1qagWflnO91ASlQo-2upjRL).

#### Do you provide the ability to communicate with players through notifications?

Openfort can notify you of transactions succeeded or reverted with [webhooks](/docs/configuration/webhooks). You can use that to send push notifications.

#### What's Openfort's business model?

At Openfort we work with any size business to connect your backend and product to the blockchain. Our business model adapts to your needs based on volume as well as the revenue and growth model your business has.

#### How can I activate "Live Mode"?

Whenever you want to go live with your product, you need to make sure to complete the details on your billing settings. This is necessary on order to top up your Account Funds.

#### What options are available for branding and white labeling?

Openfort offers headless smart accounts which means that you can customize your own UI and experience. You can decide to use any popular framework or completely integrate it within you game (zero popups).


## Pay Gas Fees with ERC20 Tokens

Gas fees can be a hurdle for many users in blockchain applications. This guide will help you configure gasless transactions where the gas is paid using an ERC20 token. Choose between dynamic or fixed-rate payment strategies.

### Charge an ERC20 with Dynamic Price

::::steps
##### Step 1: Select the Contract You Want to Interact With

* Add your collectible's smart contract.
* Define the contract function you want to use (e.g., `mint`).

**API**

```bash [Terminal]
curl https://api.openfort.io/v1/contracts \
  -u "$YOUR_SECRET_KEY:" \
  -d 'name=NFT Contract' \
  -d 'chainId=80002' \
  -d 'address=contract_address'
```

**Dashboard**
![Add Contract](https://blog-cms.openfort.io/uploads/Add_contract_7634c46ab8.png)

##### Step 2: Set Up a Dynamic ERC20 Policy

* Create a new policy and select the strategy `charge dynamic amount of ERC20`.
* Select the ERC20 token contract and exchange rate.
* Link the imported contract and the function you want to sponsor.

:::note
If you want to update the dynamic rate programmatically, contact us.
:::

**API**

```bash [Terminal]
curl https://api.openfort.io/v1/policies \
  -u "$YOUR_SECRET_KEY:" \
  -d 'name=My Policy' \
  -d 'chainId=80002' \
  -d 'strategy[sponsorSchema]=charge_custom_tokens' \
  -d 'strategy[tokenContract]=con_...' \
  -d 'strategy[tokenContractAmount]=1' 
```

```bash [Terminal]
curl https://api.openfort.io/v1/policies/:id/policy_rules \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d type="contract_functions" \
  -d functionName="All functions" \
  -d contract="con_..."
```

**Dashboard**
![Dynamic Pricing Policy](https://blog-cms.openfort.io/uploads/gas_payment_erc20_f380972463.png)

##### Step 3: Create a Gasless Transaction

* Add `chainId`.
* Add the contract.
* Add the policy.
* Add the function you want to interact with.

:::note
You can make a transaction without a registered user or account deployed at the time of interaction. Once you make the transaction, a `playerId` and `accountId` will be created.
:::

```bash [Terminal]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d 'chainId=80002' \
  -d 'optimistic=true' \
  -d 'policy=policy_id' \
  -d 'interactions[0][contract]=contract_address' \
  -d 'interactions[0][functionName]=mint' \
  -d 'interactions[0][functionArgs][0]=sender_address_or_id'
```

##### Step 4: (Optional) Add the Account or Player

* Add an account or player to specify the user.

```bash [Terminal]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d 'chainId=80002' \
  -d 'policy=policy_id' \
  -d 'account=account_id' \
  -d 'optimistic=true' \
  -d 'interactions[0][contract]=contract_address' \
  -d 'interactions[0][functionName]=mint' \
  -d 'interactions[0][functionArgs][0]=sender_address_or_id'
```
::::

### Charge an ERC20 with Fixed Price

::::steps
##### Step 1: Select the Contract You Want to Interact With

* Add your collectible's smart contract.
* Define the contract function you want to use (e.g., `mint`).

**API**

```bash [Terminal]
curl https://api.openfort.io/v1/contracts \
  -u "$YOUR_SECRET_KEY:" \
  -d 'name=NFT Contract' \
  -d 'chainId=80002' \
  -d 'address=contract_address'
```

**Dashboard**
![Add Contract](https://blog-cms.openfort.io/uploads/Add_contract_7634c46ab8.png)

##### Step 2: Set Up a Fixed ERC20 Policy

* Create a new policy and select the strategy `charge fixed amount of ERC20`.
* Specify the ERC20 token contract and the fixed amount to charge.
* Link the imported contract and the function you want to sponsor.

**API**

```bash [Terminal]
curl https://api.openfort.io/v1/policies \
  -u "$YOUR_SECRET_KEY:" \
  -d 'name=Fixed Policy' \
  -d 'chainId=80002' \
  -d 'strategy[sponsorSchema]=charge_fixed_rate' \
  -d 'strategy[tokenContract]=contract_address' \
  -d 'strategy[tokenContractAmount]=1'
```

**Dashboard**
![Fixed Pricing Policy](https://blog-cms.openfort.io/uploads/fixed_gas_policy_example.png)

##### Step 3: Create a Gasless Transaction

* Add `chainId`.
* Add the contract.
* Add the policy.
* Add the function you want to interact with.

:::note
You can make a transaction without a registered user or account deployed at the time of interaction. Once you make the transaction, a `playerId` and `accountId` will be created.
:::

```bash [Terminal]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d 'chainId=80002' \
  -d 'optimistic=true' \
  -d 'policy=pol_...' \
  -d 'interactions[0][contract]=con_...' \
  -d 'interactions[0][functionName]=mint' \
  -d 'interactions[0][functionArgs][0]=sender address or Id'
```

##### Step 4: (Optional) Add the Account or Player You're Using

* Add account or add player

```bash [Terminal]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d 'chainId=80002' \
  -d 'policy=pol_...' \
  -d 'account=acc...' or 'player=pla...' \
  -d 'optimistic=true' \
  -d 'interactions[0][contract]=con_...' \
  -d 'interactions[0][functionName]=mint' \
  -d 'interactions[0][functionArgs][0]=sender address or Id'
```
::::


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Gas sponsorship

Whether you're building a game, marketplace, or any web3 application, these policies give you the tools to create seamless user experiences by controlling how transaction fees are handled.

### What's a Gas Manager?

A gas manager is at the heart of how Openfort handles transaction fees. Think of it as your control center for managing how and when your application will sponsor user's gas fees.

Start by visiting the [Gas Policy tab](https://dashboard.openfort.io/policies) in your dashboard and clicking `Add Policy`. From there, you'll be able to configure how you want to handle transaction fees.

### Sponsoring gas fees

When it comes to sponsoring gas fees, you have two main payment methods available:

#### Paying with credit card

The simplest way to get started is by adding [balance credit](https://dashboard.openfort.io/settings/project/billing) to your account. When you choose this method, gas costs are automatically deducted from your balance as transactions occur. This is particularly useful when you're ready to go live with your project, as it's required for `livemode` operations.

#### Paying with native tokens

For more advanced use cases, you can use network native tokens (like ETH on Base). This method involves depositing tokens to Openfort's Paymaster contract. Here's how to set it up:

Check the entity addresses page to find the paymaster's address in your network.

:::note
Tokens deposited in this contract can always be withdrawn by the owner, and you can control its balance at any time by checking its balance.
:::

:::steps
##### Deposit your tokens using the `depositFor` function

<div align="center">
  <img alt="deposit native tokens" src="https://blog-cms.openfort.io/uploads/deposit_native_tokens_f96cedc838.png" width="80%" height="80%" />
</div>

##### Register your EOA wallet

Go to the [backend wallets](https://dashboard.openfort.io/accounts) page to register your EOA wallet.

##### Sign and validate your signature

Click on advanced configuration (see the video below).

<VideoSnippet title="Sponsor Demo" src="lWpcJJOcaLs" />

##### Configure your policy

Select "Sponsor gas with your tokens" when editing or creating a policy.

<div align="center">
  <img alt="deposit native tokens" src="https://blog-cms.openfort.io/uploads/deposit_address_6a7ede434e.png" width="60%" height="60%" />
</div>
:::

:::warning
When using a strategy that supports payment in ERC-20 tokens (i.e. `charge_custom_tokens` or `fixed_rate`), the backend wallet will receive the tokens users pay for gas fees.
:::

### Optional: Using external paymasters

For those needing custom solutions, Openfort supports integration with external paymasters. This feature is particularly useful when you have specific requirements for gas sponsorship that go beyond the standard options. Note that when using external paymasters, you'll need to use the `pay_for_user` strategy.

:::info
When using an external paymaster, the only supported `strategy` is `pay_for_user`.
:::

You can set up an external paymaster either through the dashboard or via the API.

#### Using the dashboard

<div align="center">
  <img alt="Using external paymasters" src="https://blog-cms.openfort.io/uploads/policy_addional_options_35e7b3096b.png" width="40%" height="40%" />
</div>

#### Using the API

```bash
# Create the paymaster object
curl https://api.openfort.io/v1/paymasters/ \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d address=80002 \
  -d url="YOUR_PAYMASTER_URL"

# Link it to your policy
curl https://api.openfort.io/v1/policies/:id \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d paymaster=pay_...
```

With these fundamentals in place, you're ready to start managing gas fees for your users. The next section will dive deeper into the different types of policies and rules you can create.


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import {
  BadgeDollarSignIcon,
  BotIcon,
  CogIcon,
  FlameIcon,
  KeyIcon,
  KeyRoundIcon,
  LinkIcon,
  Users2Icon,
  UsersIcon,
} from "lucide-react";

## Configuration

The Openfort configuration settings determine how your application interacts with our services.

Here are the main configuration options available for you to jump right in:

<HoverCardLayout>
  <HoverCardLink description="Manage API keys for your Openfort application." href="/configuration/api-keys" title="Api Keys" icon={KeyRoundIcon} color="#0EA5E9" />

  <HoverCardLink description="Manage user authentication methods and providers." href="/configuration/users" title="Authentication" icon={Users2Icon} color="#10B981" />

  <HoverCardLink description="List of Chains supported by Openfort." href="/configuration/chains" title="Supported Blockchains" icon={BadgeDollarSignIcon} color="#F59E0B" />

  <HoverCardLink description="Configure AI Tooling for your Openfort application." href="/configuration/ai-tooling/llms" title="AI Tooling" icon={BotIcon} color="#8B5CF6" />

  <HoverCardLink description="Configure Webhooks for your Openfort application." href="/configuration/webhooks" title="Webhooks" icon={LinkIcon} color="#6366F1" />

  <HoverCardLink description="Manage gas sponsorship settings for your Openfort application." href="/configuration/gas-sponsorship" title="Gas Sponsorship" icon={FlameIcon} color="#EF4444" />
</HoverCardLayout>


## Events

### Why use events?

When building Openfort integrations, you might want your applications to receive events as they occur in your Openfort accounts, so that your backend systems can execute actions accordingly.

You can configure notifications via the API to be notified about events that happen in your Openfort account or on-chain.

By default, Openfort will send a notification to the specified subscriptions every 24 hours.

### Create an event

Notification objects are the core of the event system. They define the name of the event and encapsulate both the trigger and subscriptions.

##### curl

```bash command-line
curl https://api.openfort.io/v1/notifications/ \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d "name=Low balance"
```

##### Node.js

```ts server.ts
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const notifications = await openfort.notifications.create({ 
  name: "Low balance"
})
```

##### .NET

```csharp Program.cs
using Openfort.SDK;
using Openfort.SDK.Model;
const openfort = new OpenfortClient(YOUR_SECRET_KEY);

const notifications = await openfort.Notifications.Create(
  new CreateNotificationRequest(
    name: "Low balance"
  )
);
```

{/* Note: You can also configure events directly from your **dashboard**. */}

### Create a trigger

Triggers define the condition that will trigger the notification.

There are 3 available triggers:

* **[Project balance trigger](https://dashboard.openfort.io/settings/project/notifications)**: Define a threshold balance of credits in your project. This is useful to control you can continue to sponsor gas fees for your users.
* **[Contract balance trigger](https://dashboard.openfort.io/developers/events)**: Check for the returned parameter of a contract call and compare it to a threshold. This is useful to control the deposited amount in a paymaster contract.
* **[Backend wallet balance trigger](https://dashboard.openfort.io/developers/events)**: Check for the balance of a backend wallet and compare it to a threshold. This is useful when you're using a backend wallet itself is paying for the gas fees of the transactions it puts onchain.

There can be more than one notification trigger per event.

##### curl

```bash command-line
curl https://api.openfort.io/v1/notification_triggers \
  -u "$YOUR_SECRET_KEY:" \
  -d 'notification=not_e0b84653-1741-4a3d-9e91-2b0fd2942f60' \
  -d 'type=project_balance_trigger' \
  -d 'threshold=1000000000'
```

##### Node.js

```ts server.ts
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const notificationtriggers = await openfort.notificationTriggers.create({ 
  notification: "not_e0b84653-1741-4a3d-9e91-2b0fd2942f60", 
  type: "project_balance_trigger", 
  threshold: "1000000000"
})
```

##### .NET

```csharp Program.cs
using Openfort.SDK;
using Openfort.SDK.Model;
const openfort = new OpenfortClient(YOUR_SECRET_KEY);

const notificationtriggers = await openfort.NotificationTriggers.Create(
  new CreateNotificationTriggerRequest(
    notification: "not_e0b84653-1741-4a3d-9e91-2b0fd2942f60", 
    type: "project_balance_trigger", 
    threshold: "1000000000"
  )
);
```

### Create a subscription

Subscriptions define the method and target of the event.

There are 2 available subscription methods:

* **Email**: Send an email to the specified target.
* **Webhook**: Send a POST request to the specified target. To learn more about receiving webhooks, check out the [webhooks guide](/docs/configuration/webhooks) and the types `notification.developer_account.balance`, `notification.contract.balance` or `notification.project.balance`.

There can be more than one notification subscription per event.

#### curl

```bash command-line
curl https://api.openfort.io/v1/notification_subscriptions \
  -u "$YOUR_SECRET_KEY:" \
  -d 'notification=not_e0b84653-1741-4a3d-9e91-2b0fd2942f60' \
  -d 'method=Email' \
  -d 'target=jaume@openfort.io'
```

#### Node.js

```ts server.ts
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const notificationsubscriptions = await openfort.notificationSubscriptions.create({ 
  notification: "not_e0b84653-1741-4a3d-9e91-2b0fd2942f60", 
  method: "Email", 
  target: "jaume@openfort.io"
})
```

#### .NET

```csharp Program.cs
using Openfort.SDK;
using Openfort.SDK.Model;
const openfort = new OpenfortClient(YOUR_SECRET_KEY);

const notificationsubscriptions = await openfort.NotificationSubscriptions.Create(
  new CreateNotificationSubscriptionRequest(
    notification: "not_e0b84653-1741-4a3d-9e91-2b0fd2942f60", 
    method: "Email", 
    target: "jaume@openfort.io"
  )
);
```


## How billing works

Our goal at Openfort is to provide a *predictable* billing system that grows with your project.

### How billing is organized

The Openfort Platform has "projects". A user can be a member of multiple projects. For example:

* `User 1`
  * `Project 1` (Smart Accounts, Auth, Payments)
  * `Project 2` (Smart Accounts, Auth, Payments)
* `User 2`
  * `Project 3` (Smart Accounts, Auth, Payments)

### Billing system

#### Project-based Billing

Each project has an individual subscription, a plan and addons. For example, `Project 1` could be on the Pro plan and `Project 2` could be on the Free plan.

![Credit Balance](https://blog-cms.openfort.io/uploads/project_billing_4f33e2d7a9.png)

#### Credit balance (Prepaid)

Each project has a credit balance. The credit balance is used to pay for the project's gas sponsorship.
Given that each proct supports all chains, the credit balance is shared across all chains.

You can monitor the gas report spending in by visiting the policy page.

![Policy Gas Reports](https://blog-cms.openfort.io/uploads/policy_report_de8f42695f.png)

#### FAQ

<details>
  <summary>
    <i>Do you only support the prepaid option?</i>
  </summary>

  No, we also support the postpaid option. Please contact us for more information
  at [joan@openfort.xyx](mailto\:joan@openfort.xyx).
</details>

<details>
  <summary>
    <i>What happens if my balance reaches 0?</i>
  </summary>

  Gas sponsorship will be disabled for your project. You can top up your balance
  to enable it again. If you want more flexible billing options, please contact us
  at [joan@openfort.io](mailto\:joan@openfort.io), where we can enable a buffer for your project.
</details>


## Security & Trust at Openfort

At Openfort, safeguarding the data and digital resources of your users is our utmost concern. We understand the crucial role we play in supporting our customers' applications and deeply value the trust placed in us.

Our system's design and infrastructure have been rigorously evaluated through multiple security assessments, audits, and penetration tests. Recognizing security as an ever-evolving challenge, we continually subject our systems to these evaluations to identify and remedy emerging vulnerabilities.

The process of embedding, maintaining, and testing security measures within your application is a significant endeavor. We dedicate ourselves to implementing industry-leading practices to protect your users' data and digital assets.

Highlighted below are key practices we employ:

### Authentication methods

Openfort facilitates a variety of authentication techniques to confirm the identities of your users, including:

* Email verification using **password-based verification**.
* **Social account** verification (Google, Apple, Twitter, Discord) through OAuth2.0.
* Ethereum wallet ownership verification using **Sign In With Ethereum (SIWE)**.
* Custom authentication methods to match your specific needs (Farcaster, etc.)

### Token Issuance & Session Management

After authentication, Openfort issues an **app Access Token (JWT):**

* Signed per application; 1-hour expiry for rapid revocation.

### Data Encryption & Backup

* **Encryption at Rest:** All databases encrypted using AES-256.
* **Regular Backups:** Full daily snapshots; transaction log backups every 5 minutes; 7-day retention.

### Network & API Security

* **TLS Everywhere:** TLS 1.2+ with HTTPS enforcement for all traffic.
* **API Secrets:** Each application has a unique API secret for server-to-server communication.
* **Rate Limiting & WAF:** Protect against brute-force and automated attacks.

***

### Wallet Configurations

Openfort offers three wallet types to meet diverse use cases:

1. **Embedded Wallet**
2. **Global wallet**
3. **Backend Wallet**

### 1. Embedded Wallet

[Documentation → Embedded Wallet Integration](/docs/products/embedded-wallet/javascript/signer/recovery)

Users retain full control of their private key, which is generated and used entirely in a secure, isolated environment in the application's domain.

#### Architecture & Workflow

1. **Key Generation:**
   * 128-bit entropy seed generated in an isolated iframe, converted to BIP-39 mnemonic, and used to derive the keypair.
2. **Private Key Handling:**
   * Private key remains in memory within the iframe and is never persisted to any database.
3. **Shamir Secret Sharing (SSS):**
   * Splits the private key into three shares:
     * **Device Share:** Stored in iframe's local storage.
     * **Auth Share:** Encrypted by Openfort; fetched via SDK on login.
     * **Recovery Share:** Encrypted with user password or Shield service.

<div align="center">
  <img alt="Non-custodial-key-generation" src="https://blog-cms.openfort.io/uploads/non_custodial_architecture_5277cc24c9.svg" width="80%" height="80%" />

  <label>Embedded wallet workflow</label>
</div>

### 2. Global wallet

[Documentation → Global wallet Setup](/docs/configuration/advanced/iframe)

A wallet used across multiple applications within the same ecosystem. Functionally identical to the embedded non-custodial wallet, but scoped for interoperability.

* **Hosting Domain:** Iframe served from the ecosystem's subdomain.
* **Use Cases:** Shared user identity and assets across games, dApps, or partner applications.

<div align="center">
  <img alt="Ecosystem signer" src="https://blog-cms.openfort.io/uploads/Group_462_1_min_a5e8dba201.png" width="90%" height="90%" />

  <label>Global wallet workflow</label>
</div>

### 3. Backend Wallet

[Documentation → Server-Side Wallets](/docs/products/server/wallet)

Backend wallets managed by Openfort's Key Management Service (KMS) for automated and internal transactions.

#### Architecture & Workflow

* **Key Generation & Storage:** Google Cloud KMS generates and stores private keys securely.
* **Usage:** Automated game transactions, escrow, contract deployments, and gasless ERC-2771 compatible actions.

<div align="center">
  <img alt="Custodial-key-generation" src="https://blog-cms.openfort.io/uploads/custodial_architecture_60e9b59b29.svg" width="80%" height="80%" />

  <label>Backend wallet workflow</label>
</div>

### Open source Key Management & Recovery

:::info
Recovery is facilitated through a service known as **Shield**, which manages the recovery share. It's important to note that the authentication share is retained within Openfort.

**Deployment Options:**
You can either use the [self-hosted](/docs/configuration/advanced/shield) or the [managed](/docs/products/embedded-wallet/javascript/signer/recovery) Shield service.

**Managed Shield service considerations**
When Openfort manages Shield on your behalf, the primary security objective is to prevent Openfort from having control over both the authentication and recovery shares simultaneously. This precaution is essential to avoid the possibility of reconstructing the private key.

To accomplish this, when registering your project with shield, you will get an extra parameter called `encryption_share`. This parameter is one of the 2 shares of a splitted encryption key (that uses the same Shamir's Secret Sharing algorithm) that is used to encrypt the recovery share. This way, Openfort can't decrypt the recovery share without the encryption share.
:::

This setup ensures that the full private key is reconstructed only in memory and never persists, requiring at least two of the three shares for reconstitution.

<div align="center">
  <img alt="player-sign-flow" src="https://blog-cms.openfort.io/uploads/Key_Generation_6ca2ab3a76.png" width="80%" height="80%" />

  <label>Account Generation</label>
</div>

<div align="center">
  <img alt="using-private-key" src="https://blog-cms.openfort.io/uploads/Key_Use_6e5713105e.png" width="80%" height="80%" />

  <label>Using Private Key</label>
</div>

<div align="center">
  <img alt="key-regeneration" src="https://blog-cms.openfort.io/uploads/Key_Regeneration_6dfceedd67.png" width="80%" height="80%" />

  <label>Using Private Key in a New Device</label>
</div>

* **Reconstruction:** Any two shares restore the private key in memory only.
* **Off-chain Recovery:** Combine Auth + Recovery or Device + Recovery.

<div align="center">
  <img alt="wallet-recovery" src="https://blog-cms.openfort.io/uploads/Account_Recovery_ec5decaf80.png" width="80%" height="80%" />

  <label>Offchain Account Recovery</label>
</div>

* **On-chain Social Recovery:** Use Guardians and smart-contract-based recovery for self-custody accounts.

<div align="center">
  <img alt="Custodial-key-generation" src="https://blog-cms.openfort.io/uploads/Onchain_Account_Recovery_7a513b16f8.png" width="80%" height="80%" />

  <label>Onchain Account Recovery</label>
</div>

### Smart Contract Accounts

Programmable wallets at the smart contract layer; custodian status depends on the underlying wallet type (non-custodial, cross-app, or custodial).

### Third-Party Reviews & Audits

* **Open-Source Libraries:** Cryptographic libraries under [GitHub](https://github.com/openfort-xyz/shamir-secret-sharing-go).
* **Security Audits:** Comprehensive audits for SSS, smart contracts, and paymasters (latest reports available upon request).

***

### Reporting Vulnerabilities

If you discover a security issue, please contact our security team at **[security@openfort.io](mailto\:security@openfort.io)**. We welcome responsible disclosure and reward impactful findings.


## Social Login

OAuth is commonly used for things like logging in to a social media account from a third-party app. It is a secure and convenient way to authenticate users and share information between applications.

### Provider Token

You can use the provider token and provider refresh token returned to make API calls to the OAuth provider. For example, you can use the Google provider token to access Google APIs on behalf of your user.


## Gas Policy Strategies & Rules

### Gas Policy Strategies

Gas policies offer three distinct strategies for handling transaction fees:

#### 1. Sponsored Transactions

Developers cover all gas fees, removing the need for users to hold native tokens.

##### Dashboard

![PolicyERC20Payment](https://blog-cms.openfort.io/uploads/charge_fix_gas_a59ea440fb.png)

##### API

```bash
curl https://api.openfort.io/v1/policies/ \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d chainId=80002 \
  -d name="Sponsored Policy" \
  -d "strategy[sponsorSchema]=pay_for_user"
```

#### 2. Dynamic ERC20 Payment

Users pay gas fees using ERC20 tokens at a dynamic exchange rate.

##### Dashboard

![PolicyERC20Payment](https://blog-cms.openfort.io/uploads/gas_payment_erc20_f380972463.png)

##### API

```bash
curl https://api.openfort.io/v1/policies/ \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d chainId=43113 \
  -d name="Dynamic ERC20" \
  -d "strategy[sponsorSchema]=charge_custom_tokens" \
  -d "strategy[tokenContract]=con_..." \
  -d "strategy[tokenContractAmount]=1"
```

#### 3. Fixed ERC20 Payment

Users pay a fixed amount of ERC20 tokens per transaction.

##### Dashboard

![PolicyERC20Payment](https://blog-cms.openfort.io/uploads/charge_fix_gas_a59ea440fb.png)

##### API

```bash
curl https://api.openfort.io/v1/policies/ \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d chainId=80002 \
  -d name="Fixed ERC20" \
  -d "strategy[sponsorSchema]=fixed_rate" \
  -d "strategy[tokenContract]=con_..." \
  -d "strategy[tokenContractAmount]=10000"
```

### Policy Rules

While strategies determine how gas fees are paid, rules define when and how your gas policy applies. Every policy needs at least one rule to function, and you can choose from three types:

| Rule Model               | Description                                                         |
| ------------------------ | ------------------------------------------------------------------- |
| **`contract_functions`** | Sponsor interactions with smart contracts.                          |
| **`account_functions`**  | Sponsor interactions with the smart account.                        |
| **`limit_rules`**        | Limit the amount of gas or number of transactions over an interval. |

#### Contract functions

These rules let you specify which smart contract interactions your policy covers. You might want to sponsor all interactions with your game contracts but not with external marketplaces, for instance.

:::note
<strong>Wildcard policy</strong><br />
Wildcard policies allow you to sponsor any transaction for any contract without the need to add them in the policy. Enable "Catch-all sponsorship".
:::

![Wildcard policy](https://blog-cms.openfort.io/uploads/wildcard_policy_ba98390abd.png)

To create a policy rule, you need first to add a contract to Openfort:

##### Add a contract

:::info
If the contract is not verified on the block explorer, you will need to enter the ABI manually. If the contract you want to interact with is a proxy contract, you will need to enter the ABI of the implementation contract.
:::

##### API

Add a contract to Openfort to an API request:

```bash
curl https://api.openfort.io/v1/contracts \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d name="SimpleNFT" \
  -d address="0x416c...354D" \
  -d chainId="80002"
```

##### Dashboard

Add a new contract by clicking the `Add contract` button in the [Asset contracts](https://dashboard.openfort.io/contracts) section, then enter:

* The name of the contract (it can be any name you want; the name is only for identification purposes)
* The network (`chainId`) where the smart contract is located.
* The address of the contract.
* The Application Binary Interface (ABI) of the contract (if not verified in the block explorer of that network).

![DashboardAddContract](https://blog-cms.openfort.io/uploads/adding_contract_dashboard_09dce2f83c.png)

Once you've selected your contract, you can then choose what function you wish to enable sponsorship for. You can select `All functions` instead to allow sponsoring all functions in that specific contract.

##### Dashboard

![policyRules](https://blog-cms.openfort.io/uploads/Screenshot_2023_05_29_at_15_53_15_40188a75a5.png)

##### API

```bash
curl https://api.openfort.io/v1/policy_rules \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d type="contract_functions" \
  -d functionName="mint" \
  -d "contract=con_..."
```

#### Account functions

These rules cover account-related operations, such as transferring ownership of accounts, managing session keys, or deploying smart accounts. They're essential for maintaining smooth account management operations within your application.

##### Dashboard

![Register Session key](https://blog-cms.openfort.io/uploads/Screenshot_2023_05_31_at_10_02_51_1cd0c933ba.png)

##### API

```bash
curl https://api.openfort.io/v1/policy_rules \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d type="account_functions"
```

#### Limit rule

Limit rules help you control usage of your gas policy. You can set limits based on:

| Rule Type           | Description                  | Example Use Case       |
| ------------------- | ---------------------------- | ---------------------- |
| Gas per Interval    | Total gas limit in timeframe | 1000 WEI/minute        |
| Gas per Transaction | Gas limit per transaction    | 100 WEI/transaction    |
| Count per Interval  | Transaction count limit      | 10 transactions/minute |

##### Dashboard

![Register Session key](https://blog-cms.openfort.io/uploads/Screenshot_2023_09_09_at_23_56_02_04f898c850.png)

##### API

```bash
curl https://api.openfort.io/v1/policy_rules \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d type="rate_limit" \
  -d functionName="gas_per_transaction" \
  -d gasLimit="1000000"
```


## Manage teams

Openfort provides granular **access controls** to manage permissions across your organizations. For each project, a user can have one of the following roles:

* Owner
* Administrator
* Member

A default project is created when you first sign in and you'll be assigned the **Owner** role. Each member can access everything under the project. Create a separate project if you need to restrict access to certain parts.

### Manage team members

To invite others to collaborate, visit your project's team settings in the [Dashboard](https://dashboard.openfort.com/settings/project/members) to send an invite link to another user's email. The invite expires after 24 hours.

:::note
If you're creating an ecosystem, head to the [ecosystem guide](#TODO).
:::

#### Permissions across roles \[#permission-across-roles]

The table below shows the corresponding permissions for each available role you can assign a team member in the Dashboard.

| Permissions             | Owner | Administrator | Member |
| ----------------------- | ----- | ------------- | ------ |
| **Members**             |       |               |        |
| Add an Administrator    | ✓     | ✓             |        |
| Remove an Administrator | ✓     | ✓             |        |
| Add a Member            | ✓     | ✓             |        |
| Remove a Member         | ✓     | ✓             |        |
| Revoke an invite        | ✓     | ✓             |        |
| Resend an invite        | ✓     | ✓             |        |
| Accept an invite        | ✓     | ✓             | ✓      |
| **Billing**             |       |               |        |
| Read invoices           | ✓     | ✓             |        |
| Read billing email      | ✓     | ✓             |        |
| Read billing address    | ✓     | ✓             |        |
| Update billing address  | ✓     | ✓             |        |
| Read payment methods    | ✓     | ✓             |        |
| Update payment methods  | ✓     | ✓             |        |
| **Projects**            |       |               |        |
| Create a project        | ✓     | ✓             | ✓      |

### Organization Overview

The default organization structure at Openfort are split in different projects. Each project has their own API Keys, players, assets and billing configuration beign completely independent one another.

<div align="center">
  <img alt="organization-architecture" src="https://blog-cms.openfort.io/uploads/dev_dashboard_f6616b5d19.svg" width="80%" height="80%" />
</div>


## Manage Users

Use the **Users** page of the dashboard to manage all registered players in your Openfort application.

### Player table

The **player table** displays all players that have been registered within Openfort for your selected application. This table only shows players who have been created through Openfort's systems, whether via direct authentication or through your application's integration. You can see important information including:

* Provider used for authentication
* API ID (unique identifier)
* Creation date
* Last sign-in timestamp

The **player table** is paginated to display 10 players at a time. You can navigate through the list using the "Previous" and "Next" buttons at the bottom. The current view range is displayed (e.g., "Viewing 1 to 10 of 838 results").

#### Player details

Clicking on a player's API ID opens the **player details** page, where you can see comprehensive information about the selected player, including:

* Details
  * API ID
  * Description
  * Creation timestamp

* Metadata
  * External User ID

* Accounts
  * Chain (e.g., Polygon)
  * Wallet address
  * Status (Active/Inactive)
  * Creation date

* Transactions
  View and manage player transactions, including asset transfers and NFT minting

* Sessions
  Monitor and manage player authentication sessions for frictionless interactions

### Authentication

The drawer displays session data such as when the user first logged into your app, when they were last seen in your app. Please note that the "Last seen" field is a rough approximation on the order of an hour from when the user was precisely last active in your app.

If you're using a third-party authentication provider instead of Openfort's authentication solution, this section will remain empty, and you'll manage your authentication through your chosen provider's interface.

#### Deleting users

From the user drawer, you can delete a user if necessary. This is an irreversible and destructive action; if the user logs into your app again, they will have a new user's ID (`playerID`), will have to relink any formerly linked accounts, and will get a new embedded wallet address. **Please take extreme care when deleting users.**

For security of user assets, Openfort does not delete the embedded wallet, and instead "soft deletes" it by disassociating it from the deleted user. If the user still has access to their login method and their wallet password, if they have set one, their wallet can be recovered after deletion.


## Webhooks

Openfort uses webhooks to push real-time notifications to you about your transactions. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

* Granting users a game item when a transaction is confirmed.
* Store all transaction events in your own database for custom reporting/retention

### Using Openfort Node SDK

Use the [Openfort SDK's](https://www.npmjs.com/package/@openfort/openfort-node) `constructWebhookEvent` method to verify an incoming webhook. Pass in the request body and the signature header. As an example, you can verify a webhook using the code below:

:::code-group
```ts [Node.js]
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  async (req: Request, _res: Response) => {
    const openfort = new Openfort('OPENFORT_SECRET_KEY')
    try {
      const event = await openfort.constructWebhookEvent(
        req.body.toString(),
        req.headers['openfort-signature']
      )
      switch (event.type) {
        case "transaction_intent.succeeded":
          console.log(`TransactionIntent ID: ${event.data.id}`)
          break
        case "transaction_intent.failed":
          console.log(`TransactionIntent ID: ${event.data.id}`)
          break
        default:
          console.log(`Unhandled event type ${event.type}`);
      }
    } catch (e) {
      console.error((e as Error).message)
    }
  }
)
```

```csharp [.NET]
[HttpPost("webhook")]
public async Task<IActionResult> Webhook()
{
    var json = await new StreamReader(HttpContext.Request.Body).ReadToEndAsync();
    WebHookEvent openfortEvent;
    try
    {
        openfortEvent = client.ConstructWebhookEvent(
            json,
            Request.Headers["openfort-signature"]
        );
        // Handle the webhook event
        var type = openfortEvent.Type;
        var transactionIntent = openfortEvent.Data;
        Console.WriteLine($"Webhook notification: {openfortEvent} found");
    }
    catch (Exception e)
    {
        Console.WriteLine($"Something failed {e}");
        return BadRequest();
    }

    var transactionIntent = openfortEvent.Data;
    Console.WriteLine($"TransactionIntent ID: {transactionIntent.Id}");

    return Ok();
}
```

```json [Webhook Object]
{
  "data": {
    "id": "tin_c502d628-5bb3-42f2-b8f5-62ba4d71df3a",
    "createdAt": 1689869074,
    "object": "transactionIntent",
    "etc":"..."
  },
  "type": "transaction_intent.succeeded",
  "date": 1689869074
}
```
:::

### Webhook object

The webhook object contains the following fields as shown in the JSON tab above.

Where the `type` will be one of the following:

* `transaction_intent.succeeded`: The transaction intent has arrived on-chain and is confirmed.
* `transaction_intent.failed`: The transaction intent has arrived on-chain and is reverted.
* `transaction_intent.cancelled`: The transaction intent parameters were not met.
* `transaction_intent.broadcast`: The transaction intent was broadcasted.
* `balance. project`: The project balance.
* `balance.contract`: The contract balance.
* `balance.dev_account`: The balance of your backend wallet.

The `data` will be a [transaction intent object](https://www.openfort.io/docs/reference/api/get-a-transaction-intent-object).

#### Register your development webhook endpoint

Register your publicly accessible HTTPS URL in the Openfort [dashboard](https://dashboard.openfort.io/webhooks). Then decide the type of webhook you want to receive.

:::tip
You can create a tunnel to your localhost server using a tool like [ngrok](https://ngrok.com/download). For example: [https://8733-191-204-177-89.sa.ngrok.io/webhooks](https://8733-191-204-177-89.sa.ngrok.io/webhooks)
:::

<div align="center">
  <img alt="transaction_intent-sign" src="https://blog-cms.openfort.io/uploads/add_webhook_dashboard_d2bd1ec8ca.png" width="90%" height="90%" />
</div>

#### Test that your webhook endpoint is working properly

:::tip
Your endpoint must return a 2xx (status code 200-299) response for the webhook to be marked as delivered. Any other statuses (including 3xx) are considered failed deliveries.
:::

Send a few test transactions to check that your webhook endpoint is receiving the events.

You can specify the number of block confirmations you want to wait before getting notified of a transaction making it on chain. The default is 0 (i.e. as soon as the transaction arrives on chain).

To do so, you need to include the `confirmationBlocks` body parameter when [creating the transaction intent](https://www.openfort.io/docs/reference/api/create-a-transaction-intent-object).

<div align="center">
  <img alt="transaction_intent-sign" src="https://blog-cms.openfort.io/uploads/webhook_logs_78c102fac5.png" width="90%" height="90%" />
</div>


### Comparison

Here are non-detailed reasons why you may want to use **Openfort** over other wallet infrastructure providers and approaches.

#### **vs Other Wallet SDKs**

* **Framework agnostic** – Works with any stack, from web to mobile SDKs including Vanilla JS for maxi,um customization.
* **Unified experience** – Embedded wallets, account abstraction, and necessary infrastructure in one SDK. No need for 4 different vendors.
* **Full control** – Customize UI, flows, and permissions exactly how you want. We love headless.

#### **vs Self-Hosted Wallet Solutions**

* **No separate infrastructure** – Runs in your app, no need to maintain a dedicated wallet backend.
* **Zero ops overhead** – No additional servers or security audits to manage.
* **Complete feature set** – AA wallets, MPC options, and in-app UX ready out-of-the-box.

#### **vs Managed Wallet Services**

* **Own your data** – Your users stay in your ecosystem; no vendor lock-in.
* **Transparent pricing** – No hidden per-user or transaction-based fees that scale unpredictably.
* **Open source** – Inspect and contribute; avoid black-box dependencies.

#### **vs Building Your Own Wallet Stack**

* **Security handled** – Battle-tested flows for wallet creation, key management, and transaction signing.
* **Save months of work** – Focus on your core product instead of low-level wallet infra.
* **Extensible design** – Add custom flows without reinventing the wheel.


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";

## Backend Wallets

Openfort provides powerful backend wallet APIs that allow developers to provision and manage wallets directly from their server-side applications. These backend wallets offer a robust set of features for creating, controlling, and automating blockchain interactions at scale.

### Features

import { Server, Shuffle, Wallet, RefreshCcw, ShieldCheck, Package, Globe } from "lucide-react";

<HoverCardLayout>
  <HoverCardLink description="Manage wallets and transactions directly from your backend." href="/products/server" title="Server Control" subtitle="Programmatic wallet ops" icon={Server} color="#FC3627" />

  <HoverCardLink description="Support Ethereum and EVM chains from one API." href="/products/server" title="Multi-chain Support" subtitle="Cross-chain ready" icon={Shuffle} color="#6B5BFF" />

  <HoverCardLink description="Choose EOAs or Smart Contract wallets for flexibility." href="/products/server" title="Flexible Custody" subtitle="Custom wallet setup" icon={Wallet} color="#FAD323" />

  <HoverCardLink description="Stay in sync with webhooks and real-time events." href="/products/server" title="State Synchronization" subtitle="Realtime blockchain state" icon={RefreshCcw} color="#0EA5E9" />

  <HoverCardLink description="Enforce custom security and transaction policies." href="/docs/products/server" title="Policy Engine" subtitle="Granular access control" icon={ShieldCheck} color="#34AADF" />

  <HoverCardLink description="Create wallets in advance for faster onboarding." href="/products/server" title="Pre-generated Wallets" subtitle="Streamlined user setup" icon={Package} color="#16A34A" />

  <HoverCardLink description="Notify your servers whenever specific user actions occur within your application. Developers can configure events such as user creation, login, or wallet creation and set up a destination URL to receive these notifications. The webhook system ensures near real-time updates for critical events." href="/products/server" title="Webhooks" subtitle="Real-time event notifications" icon={Globe} color="#0EA5E9" />
</HoverCardLayout>


## Pricing

| Product              | Description                                                                                                             | Pricing                                        | Value Proposition                                                                                                                                                                           |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Embedded Wallets** | Seamless, invisible wallets for your users. Integrate onboarding, authentication, and account abstraction in one stack. | [See pricing](https://www.openfort.io/pricing) | **Faster integration, lower costs:** Open source and vertically integrated, so you don’t need 3–4 separate vendors. Easy to self-host or migrate anytime—no vendor lock-in.                 |
| **Global Wallets**   | Launch your own global, cross-app wallet (like Abstract Wallet or Coinbase Smart Wallet). Modular and flexible.         | [See pricing](https://www.openfort.io/pricing) | **Own your wallet ecosystem:** Build a branded wallet that works across apps. Full modularity: bring your own auth (Privy, Dynamic, WebAuthn) and any smart account (4337, 7702, Biconomy). |
| **Rapidfire**        | Open source, free-to-use authentication and wallet connector UI. Competes with Porto, but with more auth options.       | Free & open source                             | **Onboard users instantly:** Plug-and-play UI for wallet connection with OAuth, email, and WebAuthn. Fully open source.                                                                     |


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";

## Global Wallets (Ecosystem SDK)

Openfort's global wallets provide a comprehensive solution for creating interoperable wallets across multiple games and applications within a unified ecosystem. These wallets offer advanced features that enhance user experience and simplify asset management for both players and developers.

:::tip
Want to start building right away? Check out the [demo](https://rapidsafe.sample.openfort.io/)
[Get started with our documentation](/docs/products/cross-app-wallet)
:::

### Features

import { Wallet, LayoutDashboard, Palette, Network, LogIn, Coins, CreditCard } from "lucide-react";

<HoverCardLayout>
  <HoverCardLink description="Integrate global wallets with libraries like Wagmi and RainbowKit." href="/products/cross-app-wallet" title="Web3 Library" subtitle="Seamless integration" icon={Network} color="#6B5BFF" />

  <HoverCardLink description="Customize the wallet UI for a branded experience." href="/products/cross-app-wallet" title="UI Customization" subtitle="Branded look & feel" icon={Palette} color="#FAD323" />

  <HoverCardLink description="Set gas fee rules and sponsor transactions across apps." href="/products/cross-app-wallet" title="Global Paymaster" subtitle="Gas sponsorship" icon={Coins} color="#34AADF" />

  <HoverCardLink description="Add a Create Wallet button for frictionless onboarding." href="/docs/products/cross-app-wallet" title="Universal Sing-On" subtitle="One-click wallet creation" icon={LogIn} color="#FC3627" />

  <HoverCardLink description="Manage global wallets and settings from one dashboard." href="/products/cross-app-wallet" title="Dashboard Setup" subtitle="Centralized control" icon={LayoutDashboard} color="#0EA5E9" />

  <HoverCardLink description="Unified balance across blockchains" href="/products/cross-app-wallet" title="Chain Abstraction" subtitle="Unified balance" icon={CreditCard} color="#0EA5E9" />
</HoverCardLayout>


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";

## Embedded Wallets (Headless Wallets)

Openfort's embedded wallets provide a seamless way to integrate wallet functionality into your application without any user interface. These embedded wallets offer a range of features to enhance user experience and security, allowing for onchain interactions.

:::tip
Want to start building right away? Check out the [demo](https://create-next-app.openfort.io/).
[Get started with our documentation](/docs/products/embedded-wallet/).
:::

### Features

import { KeyRound, ShieldCheck, Zap, LogIn, Wallet, Settings } from "lucide-react";

<HoverCardLayout>
  {/* Export Keys */}

  <HoverCardLink description="Transfer account ownership securely on-chain without exposing keys." href="/products/embedded-wallet" title="Export Keys" subtitle="Full control over assets" icon={KeyRound} color="#0EA5E9" />

  {/* Smart Wallet */}

  <HoverCardLink description="Enable ERC-4337 features like gasless transactions and batching." href="/docs/products/embedded-wallet" title="Smart Wallet" subtitle="Advanced account features" icon={Wallet} color="#6B5BFF" />

  {/* Session Keys */}

  <HoverCardLink description="Create temporary keys for popupless preapproved transactions." href="/products/embedded-wallet" title="Session Keys" subtitle="Scoped temporary keys" icon={Zap} color="#FAD323" />

  {/* Sign Messages */}

  <HoverCardLink description="Sign messages and off-chain data securely without pop-ups." href="/products/embedded-wallet" title="Sign Messages" subtitle="Secure signing flows" icon={Settings} color="#FC3627" />

  {/* Security Shield */}

  <HoverCardLink description="Non-custodial accounts with extra layers of protection." href="/docs/products/embedded-wallet" title="Security Shield" subtitle="Advanced protection" icon={ShieldCheck} color="#34AADF" />

  {/* State Management */}

  <HoverCardLink description="Track transactions and manage nonces seamlessly." href="/products/embedded-wallet" title="State Management" subtitle="Reliable sync" icon={Settings} color="#00BFA6" />
</HoverCardLayout>

<HoverCardLayout>
  {/* Authentication Suite */}

  <HoverCardLink description="Flexible login options like Social OAuth, SIWE, and password." href="/products/embedded-wallet" title="Authentication" subtitle="Social, SIWE, Password" icon={LogIn} color="#0EA5E9" />

  <HoverCardLink description="Connect wallets like MetaMask and Coinbase easily." href="/products/embedded-wallet" title="Wallet Connector" subtitle="Openfort Kit" icon={Wallet} color="#6B5BFF" />

  <HoverCardLink description="Enable guest mode and custom OIDC authentication flows." href="/products/embedded-wallet" title="3rd Party Auth" subtitle="Flexible user flows" icon={Settings} color="#FC3627" />
</HoverCardLayout>


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import { Wallet, Layers, PackageOpen, Zap, Puzzle } from "lucide-react";

## Welcome to Openfort

Openfort builds secure wallet infrastructure and user authentication to enable better financial products. We provide embedded wallet solutions and global wallet capabilities that allow applications to seamlessly integrate digital asset functionality for users, businesses, and automated systems.

### Why Openfort?

*Authentication and wallet management have traditionally been complex and fragmented. Many solutions require developers to stitch together multiple services or write extensive custom code to support secure onboarding, embedded wallets, and global wallet experiences. Openfort is designed to solve these challenges by providing a unified, developer-friendly, and open-source platform for authentication and wallet infrastructure—making it easy to integrate secure, seamless digital asset functionality into any application.*

<HoverCardLayout>
  <HoverCardLink
    description="Get started with Openfort by creating a new project and obtaining your API keys."
    href="https://dashboard.openfort.io"
    title="Get started"
    subtitle="Openfort dashboard"
    img={{
    src: "/img/icon.svg",
    alt: "Openfort Icon",
    className: "rounded-none",
  }}
    color="#fc3627"
    external
  />

  <HoverCardLink description="Try our embedded wallet sample to explore Openfort's features and capabilities." href="https://create-next-app.openfort.io" title="Try our demo" subtitle="Auth sample" icon={Puzzle} color="#fad323" external />

  <HoverCardLink
    description="Join our community for support, updates, and discussions."
    href="https://t.me/openfort"
    title="Join our community"
    subtitle="Direct support"
    img={{
    src: "/img/icons/telegram-icon2.svg",
    alt: "Telegram Icon",
    className: "rounded-none p-0.5",
  }}
    color="#34aadf"
    external
  />
</HoverCardLayout>

### Chose the right product for

<HoverCardLink title="Embedded Wallet" subtitle="Invisible In-App Wallets" description="Seamless onboarding with in-app non-custodial wallets. Perfect for games and apps on mobile and web. Power your UX with crypto rails without breaking the flow." href="/docs/products/embedded-wallet/" icon={Wallet} color="#FC3627" />

<HoverCardLink title="Global Wallet" subtitle="Abstract Wallet Framework" description="Launch your own global smart wallet solution, like Coinbase Smart Wallet. Modular design: choose any auth (Privy, Dynamic, WebAuthn) and any smart account (ERC-4337, EIP-7702, Biconomy, ZeroDev, etc.)." href="/docs/products/global-wallet" icon={Layers} color="#6B5BFF" />

<HoverCardLink title="Backend Wallet" subtitle="Server-Side Signing" description="Secure infrastructure to create and manage wallets for your backend services. Ideal for minting, transactions, and game operations that need a trusted signer." href="/docs/products/backend-wallet/" icon={PackageOpen} color="#1E90FF" />

<HoverCardLink title="Rapidfire" subtitle="Branded Openfort Wallet" description="Use Openfort branded wallet. Built-in account abstraction, transactions, and signing in real-time. Open-source and free, with OAuth and email auth options included." href="https://rapidfire.sample.openfort.io/" icon={Zap} color="#FAD323" />


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";

## RapidFire Wallet

Rapidfire is the branded wallet from Openfort. It's an opensource implementation that you can integrate for free to have all the wallet capabilities.

:::tip
Want to start building right away? Check out the [demo](https://rapidfire.sample.openfort.io/)
[Get started with our documentation](/docs/products/cross-app-wallet/usage/web-app-wagmi)
:::

### Features

import { Mail, KeyRound, Droplet, Lock, CreditCard, Globe, Palette } from "lucide-react";

<HoverCardLayout>
  {/* Email, social & passkeys */}

  <HoverCardLink description="Offer login via email, social accounts, and passkeys." href="/products/cross-app-wallet/usage/libraries" title="Auth methods" subtitle="Email, Social & Passkeys" icon={Mail} color="#FC3627" />

  {/* Authentication with SIWE */}

  <HoverCardLink description="Authenticate users with Sign-In with Ethereum." href="/products/cross-app-wallet/usage/web-app-wagmi" title="Authentication (SIWE)" subtitle="Web3-native login" icon={KeyRound} color="#6B5BFF" />

  {/* Natively gasless */}

  <HoverCardLink description="Enable gasless transactions out of the box." href="/products/cross-app-wallet/usage/web-app-wagmi" title="Natively Gasless" subtitle="User-friendly transactions" icon={Droplet} color="#0EA5E9" />

  {/* Permission */}

  <HoverCardLink description="Control user permissions and access levels." href="/products/cross-app-wallet/usage/web-app-wagmi" title="Permission" subtitle="Granular control" icon={Lock} color="#16A34A" />

  {/* Payment flows */}

  <HoverCardLink description="Integrate seamless payment and checkout flows." href="/products/cross-app-wallet/usage/web-app-wagmi" title="Payment Flows" subtitle="Smooth user payments" icon={CreditCard} color="#FAD323" />

  {/* No app or extension needed */}

  <HoverCardLink description="Works without extra apps or browser extensions." href="/products/cross-app-wallet/usage/web-app-wagmi" title="No App or Extension" subtitle="Frictionless onboarding" icon={Globe} color="#34AADF" />

  {/* Customizable theme */}

  <HoverCardLink description="Match wallet UI to your brand’s design." href="/products/cross-app-wallet/usage/web-app-wagmi" title="Custom Theme" subtitle="Fully brandable" icon={Palette} color="#6B7280" />
</HoverCardLayout>


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import { Puzzle } from "lucide-react";

## Openfort SDKs \[The recommended way to interact with the Openfort API is by using one of our official SDKs]

### Client-side SDKs

Openfort client-side helper libraries (also known as client-side SDKs) reduce the amount of work required to handle signers and session keys.

#### With Auth UI

<HoverCardLink
  title="Wallet Connector (Openfort Kit)"
  subtitle="The best way to get started with Openfort"
  description={`A robust React component library for integrating wallet connections into your dApp.\nProvides a simple and customizable way to connect wallets.`}
  href="/products/embedded-wallet/react/kit"
  img={{
  src: "/img/icons/libraries/react-icon.svg",
  alt: "React",
}}
  color="#61DAFB"
/>

#### Without Auth UI (Headless)

<HoverCardLayout>
  <HoverCardLink
    description="React SDK for mobile applications."
    href="/products/embedded-wallet/react-native"
    title="React Native"
    subtitle="Mobile"
    img={{
    src: "/img/icons/libraries/react-native-icon.svg",
    alt: "React",
  }}
    color="#61DAFB"
  />

  <HoverCardLink
    description="For web applications using React, Vite, Angular, or vanilla JavaScript."
    href="/products/embedded-wallet/javascript"
    title="Vanilla JavaScript"
    subtitle="Core SDK"
    img={{
    src: "/img/icons/javascript-icon.svg",
    alt: "JavaScript Icon",
  }}
    color="#F7DF1E"
    links={{
    github: "https://github.com/openfort-xyz/openfort-js"
  }}
  />

  <HoverCardLink
    description="For game development with Unity engine."
    href="/products/embedded-wallet/unity"
    title="Unity"
    subtitle="Game Development"
    img={{
    src: "/img/icons/libraries/unity.svg",
    alt: "Unity Icon",
    invertOnDark: true,
  }}
    color="#aaa"
    links={{
    github: "https://github.com/openfort-xyz/openfort-csharp-unity"
  }}
  />
</HoverCardLayout>

### Server-side SDKs and API

Openfort server-side helper libraries (also known as server-side SDKs) reduce the amount of work required to use Openfort's REST APIs, starting with reducing the boilerplate code you have to write.

<HoverCardLayout>
  <HoverCardLink
    title="Node.js"
    subtitle="An isomorphic Javascript client for Openfort."
    description="NodeJS SDK for interacting with Openfort's infrastructure."
    href="https://openfort.apidocumentation.com"
    className="col-span-2"
    img={{
    src: "/img/icons/libraries/node.svg",
    alt: "Node.js Icon",
  }}
    color="#fc3627"
    links={{
    github: "https://github.com/openfort-xyz/openfort-node"
  }}
  />

  <HoverCardLink
    title=".NET"
    subtitle="A .NET client for Openfort."
    description="C# SDK for interacting with Openfort's infrastructure."
    href="https://openfort.apidocumentation.com"
    img={{
    src: "/img/icons/libraries/c-sharp-icon.svg",
    alt: "Node.js Icon",
  }}
    color="#fad323"
    links={{
    github: "https://github.com/openfort-xyz/openfort-csharp"
  }}
  />
</HoverCardLayout>


import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import { Lock, Puzzle } from "lucide-react";

## Openfort samples \[Browse the official Openfort repositories for SDKs, smart contracts, and integrations to accelerate your development.]

Explore the library of sample projects using Openfort.

:::tip
Find even more samples in our [GitHub repository](https://github.com/openfort-xyz/samples#readme).
:::

### Embedded Wallet

#### With Auth UI

<HoverCardLink
  title="Wallet Connector Sample"
  subtitle="Using @openfort/openfort-kit"
  description={`A robust React component library for integrating wallet connections into your dApp.\nProvides a simple and customizable way to connect wallets.`}
  href="https://github.com/openfort-xyz/openfort-kit/tree/main/examples"
  img={{
  src: "/img/icons/libraries/react-icon.svg",
  alt: "React",
}}
  color="#61DAFB"
  links={{
  docs: "/products/embedded-wallet/react/kit",
  sample: "https://kit.openfort.io/",
}}
/>

#### Without Auth UI (Headless)

<HoverCardLayout>
  <HoverCardLink
    title="React Native"
    subtitle="Using react-native"
    description="React SDK for mobile applications."
    href="https://github.com/openfort-xyz/react-native-auth-sample"
    img={{
    src: "/img/icons/libraries/react-native-icon.svg",
    alt: "React",
  }}
    color="#61DAFB"
    links={{
    docs: "/products/embedded-wallet/react-native",
  }}
  />

  <HoverCardLink
    title="Javascript Sample"
    subtitle="Using openfort-js"
    description="Authenticate users and create embedded wallets in your web applications."
    href="https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample"
    img={{
    src: "/img/icons/javascript-icon.svg",
    alt: "JavaScript Icon",
  }}
    color="#F7DF1E"
    links={{
    sample: "https://openfort-auth-non-custodial.vercel.app/",
    docs: "/products/embedded-wallet/javascript",
  }}
  />

  <HoverCardLink
    title="Wagmi Sample"
    subtitle="wagmi + openfort-js"
    description="Sample using wagmi with Openfort's JavaScript SDK."
    href="https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample"
    img={{
    src: "/img/icons/wagmi-icon.svg",
    alt: "Wagmi Icon",
    invertOnDark: true,
  }}
    color="#aaa"
    links={{
    sample: "https://openfort-auth-non-custodial.vercel.app/",
    docs: "/products/embedded-wallet/javascript",
  }}
  />

  <HoverCardLink
    title="Third-party auth sample"
    subtitle=""
    description="Firebase authentication with Openfort's embedded wallet."
    href="https://github.com/openfort-xyz/embedded-wallet-firebase-auth-sample-nextjs"
    img={{
    src: "/img/icons/firebase-icon.svg",
    alt: "JavaScript Icon",
  }}
    color="#ffca27"
    links={{
    sample: "https://firebase-auth-embedded-wallet.vercel.app/",
    docs: "/products/embedded-wallet/javascript/auth/external-auth",
  }}
  />

  <HoverCardLink
    description="For game development with Unity engine."
    href="https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer"
    title="Unity"
    subtitle="Webgl sample"
    img={{
    src: "/img/icons/libraries/unity.svg",
    alt: "Unity Icon",
    invertOnDark: true,
  }}
    color="#aaa"
    links={{
    sample:
      "https://openfort-xyz.github.io/sample-unity-webgl-embedded-signer/",
    docs: "/products/embedded-wallet/unity",
  }}
  />
</HoverCardLayout>

### Global Wallet (Ecosystem)

<HoverCardLink
  title="Global Wallet Example - Rapidfire ID"
  subtitle=""
  description="A sample ecosystem wallet that works across multiple applications."
  href="https://github.com/openfort-xyz/ecosystem-sample"
  img={{
  src: "/img/icon.svg",
  alt: "Openfort Icon",
  className: "rounded-none",
}}
  color="#fc3627"
  links={{
  sample: "https://rapidfire.sample.openfort.xyz/",
  docs: "/products/cross-app-wallet",
}}
/>

#### Server-side

<HoverCardLink
  title="Create encryption sessions"
  subtitle="Using @openfort/openfort-node"
  description="A Node.js sample to bootstrap encryption sessions with Openfort. Needed to create signers."
  href="https://github.com/openfort-xyz/auth-sample-backend"
  icon={Lock}
  color="#aabbcc"
  links={{
  docs: "/products/embedded-wallet/javascript/signer/recovery",
}}
/>


## Postman API Suite

Interested in trying out Openfort's APIs via Postman? We've got you covered! Postman offers a seamless experience for testing APIs, and we've created specialized collections just for you.

We recommend using our quality assurance (QA) testing use cases, and importing our [Postman collection](https://api.postman.com/collections/26730089-47206a29-8371-4fe2-82ce-6cb893f4bfa7?access_key=PMAT-01HZSY9PS64FCGCKXSB9FG7J0K) to aid you in the testing process.

### Getting Started

* **Fork:** Clone the collection, keeping a link to the original.
* **View**: Test the API instantly without importing to Postman.
* **Import**: Clone the collection without the original link.

### Configuration

To use the collection, navigate to the collection you just imported and click Variables. Copy your testmode Stripe secret key from the Openfort Dashboard, and paste it into the Initial Value field. After you complete this step, you're ready to begin making requests.

<div align="left">
  <a
    href={
    "https://app.getpostman.com/run-collection/26730089-47206a29-8371-4fe2-82ce-6cb893f4bfa7?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D26730089-47206a29-8371-4fe2-82ce-6cb893f4bfa7%26entityType%3Dcollection%26workspaceId%3Df3ba6d82-fd73-4d1d-bcfa-5aabb3926e02"
  }
  >
    <img alt="Run in Postman" src="https://run.pstmn.io/button.svg" width="15%" height="15%" />
  </a>
</div>

#### Authorization

Input your API key in the "Authorization" tab. For advanced testing, store the API key as a Postman variable.


## Iframe Service

The iframe service is a crucial element in ensuring the security and privacy of a user's private keys. The isolated iframe operates as a secure environment, managing the private key and executing wallet operations. This setup is pivotal because it keeps the private key confined to an in-memory state within the iframe, never storing it in a database or allowing it to persist beyond the session. This isolation also means the private key is protected from potential exposure or theft, as it's inaccessible to both the app's code and the Openfort SDK.

:::tip[Recommendation]
Self hosting and writing your own iframe communication code is a complex task. We recommend using the [@openfort/openfort-js](https://www.npmjs.com/package/@openfort/openfort-js) to interact with the iframe. The SDK provides a simple and secure way to communicate with the iframe service.
:::

This guide provides a step-by-step approach to downloading and running the openfort/iframe Docker image, which is hosted on Docker Hub. By following these instructions, you will be able to set up and host the image on your local machine or server environment.

### Hosting the iframe

::::steps
#### Prerequisites

Before you begin, make sure you have the following installed:

* **Docker**: Ensure you have Docker installed on your machine. If not, download and install Docker from the [official website](https://docs.docker.com/engine/install/).

#### Step 1: Pulling the Docker Image

To start, you'll need to pull the openfort/iframe image from Docker Hub. Open a terminal and run the following command:

:::code-group
```bash [Terminal]
docker pull openfort/iframe
```

```bash [Specific Version]
docker pull openfort/iframe:tagname
```
:::

This command downloads the latest version of the openfort/iframe image to your local machine. If you need a specific version, you can tag it like this: `openfort/iframe:tagname`.

You can also find the Docker image on [Docker Hub](https://hub.docker.com/r/openfort/iframe).

#### Step 2: Running the Docker Image

Once the image is pulled, you can run it as a container. To do this, execute the following command in your terminal:

```bash [Terminal]
docker run -d -p 8080:80 openfort/iframe
```

Here, `-d` runs the container in detached mode (in the background), and `-p 8080:80` maps port 80 of the container to port 8080 on your host machine. Adjust the port settings as needed for your environment.

#### Step 3: Accessing the Application

After the container starts, you can access the application by opening a web browser and navigating to `http://localhost:8080`. You should see the Openfort iframe service running and ready for use.
::::

### Interacting with the iframe

The iframe service provides a set of APIs that allow you to interact with the embedded wallet. These APIs enable you to create, sign, and broadcast transactions, as well as manage accounts and keys.

#### Communicating with the iframe

We have created a client-side library to help you interact with the iframe service. You can find the library on [GitHub](https://github.com/openfort-xyz/iframe-client).

:::tip[iframe Client SDK]
A client library to communicate with the Openfort iframe service. This library provides a simple and secure way to interact with the iframe service for key generation and signing transactions.
:::


## Shield Service

:::info[Developer Guide]
This guide is for developers that want to self-host Shield (automatic recovery) for their users. If you are a user looking to use Shield and to understand how it works, please refer to the [user guide](/docs/products/embedded-wallet/javascript/signer/recovery).
:::

In automatic recovery, Openfort uses Shield to encrypt and store the **recovery share** of the embedded wallet on behalf of the user.

:::warning[Security Consideration]
In the case you do not require a passcode from your users, you are trusting whoever hosts Shield's infrastructure as well as setting the user's authentication token as the sole root of trust for their wallet. We generally recommend you prompt users to set a recovery passcode upfront, especially as assets in a wallet grow.
:::

### Self-Hosted Shield

You can self-host the Shield service to maintain full control over your users' recovery data:

:::code-group
```bash [GitHub Repository]
# Clone the Shield repository
git clone https://github.com/openfort-xyz/shield
```

```bash [Installation]
# Install dependencies
npm install
```

```bash [Configuration]
# Configure your Shield instance
cp .env.example .env
# Edit .env with your settings
```
:::

:::tip[Repository]
**Shield** - Self-hostable Shield service for automatic wallet recovery

* **Repository**: [github.com/openfort-xyz/shield](https://github.com/openfort-xyz/shield)
* **Description**: Complete Shield service implementation for self-hosting
:::

### Communicating with Shield

We have created a client-side library to help you interact with the Shield service:

:::code-group
```bash [Installation]
npm install @openfort/shield-js
```

```typescript [Usage]
import { ShieldClient } from '@openfort/shield-js'

const shieldClient = new ShieldClient({
  baseUrl: 'https://your-shield-instance.com'
})
```
:::

:::tip[Client SDK]
**Shield Client SDK** - Official client library for Shield communication

* **Repository**: [github.com/openfort-xyz/shield-js](https://github.com/openfort-xyz/shield-js)
* **Description**: A client library to communicate with the Openfort Shield service
:::

### Next Steps

* [User Guide](/docs/products/embedded-wallet/javascript/signer/recovery) - Learn how Shield works for end users
* [Shield Repository](https://github.com/openfort-xyz/shield) - Self-host the Shield service
* [Shield Client SDK](https://github.com/openfort-xyz/shield-js) - Integrate with Shield programmatically


## Using AI-powered IDEs with our docs

We've created `.txt` files that you can easily copy and paste into your large language model (LLM) of choice to give more context on how all of our Openfort APIs works and significantly improve the accuracy of your AI-generated code.

### Use Openfort docs llms-full.txt file

Copy paste the following into an LLM or AI Agents like Cursor or Replit to help them easily understand the correct syntax of the Openfort SDKs

2. Navigate to **Settings > Features > Docs**
3. Select "Add new doc: and paste the following IRL:

```
https://www.openfort.io/docs/llms-full.txt
```

3. Use `@docs -> Openfort` ro reference Openfort's docs in your code.

#### Relevant files

* **[Directory structure (llms.txt)](https://www.openfort.io/docs/llms.txt)**
* **[Full documentation (llms-full.txt)](https://www.openfort.io/docs/llms-full.txt)**


## Custom Generic Auth Token

Generic authentication serves as an alternative for those utilizing their own authentication server. This method accommodates various authentication types not currently supported, such as `GitHub`, or bespoke systems.

Essential steps and requirements for generic authentication through an endpoint include:

* Post-login, generate a public identifier to recognize the user.
* Relay this identifier to the private key to initiate wallet creation.
* An endpoint you provide will be contacted to confirm the user's identity, upon which we'll create a wallet if the information is valid.

You'll need to supply an endpoint for identity verification.

Additional headers for request authentication can be passed and will accompany every verification request to your endpoint.

### Authenticating Users with Generic Authentication

#### Configure your server

Within the server that handles authentication requests, you'll need to implement an endpoint responsible for verifying the user's identity. This endpoint should accept a `POST` request with a JSON body containing the `payload` field, which corresponds to the user's public identifier.

```json
{
  "payload": "public_identifier" // you can put any data you want here (as long as it's a string)
}
```

After returning a JSON response, the SDK will create a wallet for the user if the response is valid. The response should contain the following fields:

```json
{
  "userId": "unique_user_id", // A unique identifier for the user, used for wallet identification if no email is provided
  "email": "user_email" // optional
}
```

:::warning
Openfort uses the `userId` field as the user identifier for **`externalUserId`**. Ensure that, across your `test` and `live` environments, different users cannot get the same `userId` value. This is crucial for maintaining unique user identification.
:::

#### Set up your provider

To set up your Custom Authentication with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/custom_auth_25d003b91c.png?updated_at=2024-03-20T23:54:40.898Z" alt="custom auth" />
</div>


## Custom OIDC compatible Auth

OIDC authentication setup is a viable choice when leveraging an external authentication provider such as `Auth0`, `Cognito`, etc., that offers JWK publication for token authenticity verification.

An OIDC authentication framework employs a public-private key pair, utilizing the private key to sign authentication tokens. The public key is made accessible via a public URL in JWKS format, typically found at `https://{domain}.com/.well-known/jwks.json`. When a user logs in, an idToken, a JWT, is produced and signed with the private key, following OIDC specifications for token field requirements. This JWT is then used within the private key to create a user wallet.

The verification of the JWT against the public key confirms its authenticity, allowing wallet generation based on the subject (user identifier) within the idToken.

Input Requirements:

* JWKS File URL (public key): Validates the token's authentic signature.
* idToken's `aud` value: Confirms that the intended recipient of the token is correct.

:::danger
From the JWT token, Openfort extracts the `sub` field, which is used as the user identifier for **`externalUserId`**. Ensure that, across your `test` and `live` environments, different users cannot get the same `sub` value. This is crucial for maintaining unique user identification.
:::

### Authenticating Users with OIDC-Compatible Authentication

#### Set up your provider

To set up your OIDC Authentication with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/oidc_auth_314e50f269.png?updated_at=2024-03-20T23:54:03.814Z" alt="oidc auth" />
</div>


## AccelByte Auth

AccelByte offers robust backend services for building and operating online games, featuring scalable cloud infrastructure, matchmaking, and cross-platform player accounts.
Their solutions focus on enhancing multiplayer experiences while providing developers with the flexibility to customize game services.

### Set up your provider

To set up Accelbyte to authenticate players with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/accelbye_auth_c2acb72c15.png?updated_at=2023-11-09T20:01:56.592Z" alt="accelbyte auth" />
</div>


## Firebase Auth

Firebase is a development platform from Google that provides a variety of tools and services to help developers build, improve, and grow their apps, with features such as databases, analytics, messaging, and crash reporting.
It emphasizes easy integration and real-time updates, enabling developers to create rich, collaborative experiences.

### Prerequisites

Head to your Project Settings in the Firebase Console and grab your Firebase Project ID.

### Set up your provider

To set up Firebase to authenticate players with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_auth_8ccee72abf.png?updated_at=2023-11-09T19:56:44.398Z" alt="firebase auth" />
</div>


## LootLocker Auth

LootLocker offers robust backend services for building and operating online games, featuring scalable cloud infrastructure, matchmaking, and cross-platform player accounts.
Their solutions focus on enhancing multiplayer experiences while providing developers with the flexibility to customize game services.

### Set up your provider

To set up LootLocker to authenticate players with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/lootlocker_auth_49c09f0ca8.png?updated_at=2023-11-30T11:02:05.677Z" alt="lootlocker auth" />
</div>


## PlayFab Auth

PlayFab provides a comprehensive suite of live game management services, including server hosting, data analytics, and liveOps utilities to streamline game development and monetization.
It is designed to empower developers with the tools needed to engage players and drive revenue, all while minimizing overhead and time to market.

### Prerequisites

To set up your PlayFab authentication with Openfort, you'll need to get the `Project ID`.

1. Visit the [PlayFab developer dashboard](https://developer.playfab.com/), select your title, and navigate to ***Settings wheel --> Title settings***:

<div align="center">
  <img src="https://blog-cms.openfort.io/uploads/image_24_da6eb344c3.png?updated_at=2023-10-26T12:11:33.581Z" width="50%" alt="playfab title settings" height="50%" />
</div>

2. In the ***API Features*** section, copy your ***Title ID***:

<div align="center">
  <img src="https://blog-cms.openfort.io/uploads/image_29_62480d0f61.png?updated_at=2023-10-26T12:11:34.085Z" width="50%" alt="get playfab title id" height="50%" />
</div>


## Supabase Auth

Supabase is an open-source alternative to Firebase. It provides a variety of tools and services to help with Postgres database, Authentication, instant APIs, Realtime, Functions, Storage and Vector embeddings.

### Prerequisites

Head to your Project Settings in the Supabase Console and grab your Project URL and anon API Key.

### Set up your provider

To set up Supabase to authenticate players with Openfort, visit your [dashboard provider settings](https://dashboard.openfort.io/players/auth/providers).

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/supabase_auth_5c920d5dd0.png?updated_at=2024-04-12T18:09:08.937Z" alt="supabase auth" />
</div>


## Custom SMTP \[How to work with passwords in Openfort Auth]

At present, you can trial the Openfort platform by sending up to **3** emails per hour via the built-in service. The default email service as a whole is offered on a best effort basis: we will do our best to maintain it and will review usage of the service on a regular basis to see if the email service should be continued.

As you progress toward production, you may find yourself wanting for a custom SMTP service in order to increase your limits. A custom SMTP server will allow you to set your own cap on the number of emails sent per hour.

Beyond rate limits, an SMTP server might also help with:

* Deliverability and Reputation Management
* Scalability
* Analytics and Tracking
* Compliance and Anti Spam measures

### How to set up SMTP

Head over to [Settings Page](https://dashboard.openfort.io/settings/configuration/auth) and hit "Enable Custom SMTP" under the SMTP Provider section.

Fill in fields below with the relevant details obtained from your custom SMTP provider:

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/SMPT_setting_509fec2568.png" alt="authenticated players" />
</div>

#### SMTP providers

You can use Openfort Auth with any major SMTP provider of your choosing. Some SMTP providers you could consider using are:

* [Twilio SendGrid](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api)
* [AWS SES](https://docs.aws.amazon.com/ses/latest/dg/send-email-smtp.html)

### Email templates

You can customize the email messages used for the authentication flows. You can edit the following email templates:

* Confirm signup
* Reset Password

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/email_templates_85f06db035.png" alt="email templates" />
</div>

### Terminology

The templating system provides the following variables for use:

| Name                 | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `{{ .state }}`       | Contains a 6-digit One-Time-Password (OTP).                              |
| `{{ .email }}`       | The user's email address.                                                |
| `{{ .redirectUrl }}` | Contains the redirect URL to confirm the email address to a new account. |

### Editing email templates

Edit your email templates on the [Email Templates](https://dashboard.openfort.io/settings/configuration/templates) page. Below is an example for a verification of a sign up:

```
Subject: Confirm Reauthentication

Body:
<h2>Confirm reauthentication</h2> 
    <p>Enter the code: {{ .state }}</p>
```


## Password-based Auth

:::note
Email authentication with global wallets
You only need to enable this toggle if you're developing an global wallets.

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/email_ecosystem_0f56b82ca0.png" alt="email setup" />
</div>
:::

### Password security

A password is more secure if it is harder to guess or brute-force. In theory, a password is harder to guess if it is longer. It is also harder to guess if it uses a larger set of characters (for example, digits, lowercase and uppercase letters, and symbols).

This table shows the *minimum* number of guesses that need to be tried to access a user's account:

| Required characters                          | Length | Guesses           |
| -------------------------------------------- | ------ | ----------------- |
| Digits only                                  | 8      | \~ 2<sup>27</sup> |
| Digits and letters                           | 8      | \~ 2<sup>41</sup> |
| Digits, lower and uppercase letters          | 8      | \~ 2<sup>48</sup> |
| Digits, lower and uppercase letters, symbols | 8      | \~ 2<sup>52</sup> |

In reality though, passwords are not always generated at random. They often contain variations of names, words, dates, and common phrases. Malicious actors can use these properties to guess a password in fewer attempts.

There are hundreds of millions (and growing!) known passwords out there. Malicious actors can use these lists of leaked passwords to automate login attempts (known as credential stuffing) and steal or access sensitive user data.

#### Password strength and leaked password protection

To help protect your users, Openfort Auth sets strength constrains of the passwords used on your project.

* Set a large minimum password length. Anything less than 8 characters is not recommended.
* Set the required characters that must appear at least once in a user's password. Use the strongest option of requiring digits, lowercase and uppercase letters, and symbols.
* Prevent the use of leaked passwords. Openfort Auth uses the open-source [HaveIBeenPwned.org Pwned Passwords API](https://haveibeenpwned.com/Passwords) to reject passwords that have been leaked and are known by malicious actors.


## Login with Apple

Openfort Auth supports using [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) on the web and in native apps for iOS, macOS, watchOS or tvOS.

### Overview

To support Sign in with Apple, you need to configure the [Apple provider in the Openfort dashboard](https://dashboard.openfort.io/players/auth/providers) for your project.

There are three general ways to use Sign in with Apple, depending on the application you're trying to build:

* Sign in on the web or in web-based apps
  * Using an OAuth flow initiated by Openfort Auth using the [Sign in with Apple REST API](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api).
* Sign in natively inside iOS, macOS, watchOS or tvOS apps using [Apple's Authentication Services](https://developer.apple.com/documentation/authenticationservices)

In some cases you're able to use the OAuth flow within web-based native apps such as with [React Native](https://reactnative.dev), [Expo](https://expo.dev) or other similar frameworks. It is best practice to use native Sign in with Apple capabilities on those platforms instead.

When developing with Expo, you can test Sign in with Apple via the Expo Go app, in all other cases you will need to obtain an [Apple Developer](https://developer.apple.com) account to enable the capability.

### Using the OAuth flow for web

Sign in with Apple's OAuth flow is designed for web or browser based sign in methods. It can be used on web-based apps as well as websites, though some users can benefit by using Sign in with Apple JS directly.

Behind the scenes, Openfort Auth uses the [REST APIs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api) provided by Apple.

#### Configuration

You will require the following information:

1. Your Apple Developer account's **Team ID**, which is an alphanumeric string of 10 characters that uniquely identifies the developer of the app. It's often accessible in the upper right-side menu on the Apple Developer Console.
2. Register email sources for *Sign in with Apple for Email Communication* which can be found in the [Services](https://developer.apple.com/account/resources/services/list) section of the Apple Developer Console.
3. An **App ID** which uniquely identifies the app you are building. You can create a new App ID from the [Identifiers](https://developer.apple.com/account/resources/identifiers/list/bundleId) section in the Apple Developer Console (use the filter menu in the upper right side to see all App IDs). These usually are a reverse domain name string, for example `com.example.app`. Make sure you configure Sign in with Apple once you create an App ID in the Capabilities list. At this time Openfort Auth does not support Server-to-Server notification endpoints, so you should leave that setting blank. (In the past App IDs were referred to as *bundle IDs.*)
4. A **Services ID** which uniquely identifies the web services provided by the app you registered in the previous step. You can create a new Services ID from the [Identifiers](https://developer.apple.com/account/resources/identifiers/list/serviceId) section in the Apple Developer Console (use the filter menu in the upper right side to see all Services IDs). These usually are a reverse domain name string, for example `com.example.app.web`.
5. Configure Website URLs for the newly created **Services ID**. The web domain you should use is the domain your Openfort project is hosted on. The redirect URL is `https://api.openfort.io/iam/v1/oauth/callback/apple`.
6. Create a signing **Key** in the [Keys](https://developer.apple.com/account/resources/authkeys/list) section of the Apple Developer Console. You can use this key to generate a secret key using the tool below, which is added to your Openfort project's Auth configuration. Make sure you safely store the `AuthKey_XXXXXXXXXX.p8` file. If you ever lose access to it, or make it public accidentally, revoke it from the Apple Developer Console and create a new one immediately. You will have to generate a new secret key using this file every 6 months, so make sure you schedule a recurring meeting in your calendar!
7. Finally, add the information you configured above to the [Apple provider configuration in the Openfort dashboard](https://dashboard.openfort.io/players/auth/providers).

<div>
  Use this tool to generate a new Apple client secret. No keys leave your browser! Be aware that this tool does not currently work in Safari, so use Firefox or a Chrome-based browser instead.
</div>

> **Apple Client Secret Generator**
>
> To generate your Apple client secret, you'll need:
>
> * Your Apple Developer Team ID
> * Your Services ID (Client ID)
> * Your private key file (.p8) downloaded from Apple Developer Console
>
> You can use online JWT generators or create the secret programmatically using the Apple Developer documentation. The secret must be regenerated every 6 months.
>
> For detailed instructions, refer to [Apple's Sign in with Apple REST API documentation](https://developer.apple.com/documentation/sign_in_with_apple/generate_and_validate_tokens).

### Using native sign in with Apple in Expo

When working with Expo, you can use the [Expo AppleAuthentication](https://docs.expo.dev/versions/latest/sdk/apple-authentication/) library to obtain an ID token that you can pass to openfort-js [`authenticateThirdParty` method](#TODO).

<div>
  When testing with Expo Go, the Expo App ID `host.exp.Exponent` will be used. Make sure to add this to the "Client IDs" list in your [Openfort dashboard Apple provider configuration](https://dashboard.openfort.io/players/auth/providers)!

  Make sure you set up **Apple Native** under third party authentication providers.
</div>

1. Have an **App ID** which uniquely identifies the app you are building. You can create a new App ID from the [Identifiers](https://developer.apple.com/account/resources/identifiers/list/bundleId) section in the Apple Developer Console (use the filter menu in the upper right side to see all App IDs). These usually are a reverse domain name string, for example `com.example.app`. Make sure you configure Sign in with Apple for the App ID you created or already have, in the Capabilities list. At this time Openfort Auth does not support Server-to-Server notification endpoints, so you should leave that setting blank. (In the past App IDs were referred to as *bundle IDs.*)
2. Register all of the App IDs that will be using your Openfort project in the [Apple provider configuration in the Openfort dashboard](https://dashboard.openfort.io/players/auth/providers) under *Client IDs*.

<div>
  If you're building a native app only, you do not need to configure the OAuth settings.
</div>


## Discord Login

To enable Discord Auth for your project, you need to set up a Discord OAuth application and add the application credentials in the Openfort Dashboard.

### Overview

Setting up Discord logins for your application consists of 3 parts:

* Create and configure a Discord Project and App on the [Discord Developer Dashboard](https://discord.com/developers).
* Add your Discord API Key and API Secret Key to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

#### Configuration

**Access your Discord account**

* Go to [discord.com](https://discord.com/).

* Click on `Login` at the top right to log in.

* Once logged in, go to [discord.com/developers](https://discord.com/developers).

* callback URL: `https://api.openfort.io/iam/v1/oauth/callback/discord`

**Create a Discord application**

* Click on `New Application` at the top right.
* Enter the name of your application and click `Create`.
* Click on `OAuth2` under `Settings` in the left side panel.
* Click `Add Redirect` under `Redirects`.
* Type or paste your `callback URL` into the `Redirects` box.
* Click `Save Changes` at the bottom.
* Copy your `Client ID` and `Client Secret` under `Client information`.

**Add your Discord credentials into your Supabase project**

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/discordauth_72052f416b.png?updated_at=2024-06-25T13:37:20.731Z" alt="Discord Auth" />
</div>


## Epic Games Login

To enable Epic Games Auth for your project, you need to set up a Epic Games OAuth application and add the application credentials in the Openfort Dashboard.

### Overview

Setting up Epic Games login for your application consists of 3 parts:

* Create and configure a Epic Project and App on the [Epic Developer Dashboard](https://dev.epicgames.com/portal/en-US/).
* Add your Epic API Key and API Secret Key to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/epicgamesauth_1a1916d474.png?updated_at=2024-06-25T13:38:28.433Z" alt="Epic Auth" />
</div>

#### Configuration

1. Create an organization on Epic Games portal and create a new project.
2. Click on `Epic Account Services` and add a new applications:

* Verify your application website and privacy policy URL
* Save the API Key (client\_id) and API Secret Key (client\_secret) for later use.

3. Set up Epic Games in Openfort:

* Go to the [Openfort dashboard](https://dashboard.openfort.io/players/auth/providers).
* Click on Epic Enabled to turn it ON.
* Enter the Epic Client ID and Epic Client Secret.


## Facebook Login

To enable Facebook Auth for your project, you need to set up a Facebook OAuth application and add the application credentials to your Openfort Dashboard.

### Overview

Setting up Facebook logins for your application consists of 3 parts:

* Create and configure a Facebook Application on the [Facebook Developers Site](https://developers.facebook.com/).
* Add your Facebook keys to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

#### Configuration

* Go to [developers.facebook.com](https://developers.facebook.com).
* Click on `Log In` at the top right to log in.

**Create a Facebook app**

* Click on `My Apps` at the top right.
* Click `Create App` near the top right.
* Select your app type and click `Continue`.
* Fill in your app information, then click `Create App`.
* This should bring you to the screen: `Add Products to Your App`. (Alternatively you can click on `Add Product` in the left sidebar to get to this screen.)

**Set up Facebook login for your Facebook app**

From the `Add Products to your App` screen:

* Click `Setup` under `Facebook Login`
* Skip the Quickstart screen, instead, in the left sidebar, click `Settings` under `Facebook Login`
* Enter your callback URI (`https://api.openfort.io/iam/v1/oauth/callback/facebook`) under `Valid OAuth Redirect URIs` on the `Facebook Login Settings` page
* Enter this in the `Valid OAuth Redirect URIs` box
* Click `Save Changes` at the bottom right

Be aware that you have to set the right use case permissions to enable Third party applications to read the email address. To do so:

Under `Build Your App`, click on `Use Cases` screen. From there, do the following steps:

* Click the Edit button in `Authentication and Account Creation` on the right side. This action will lead to the other page.
* `public_profile` is set by default, so make sure it and `email` have status of **Ready for testing** in the redirected page.
* If not, click the **Add** button in email on right side.

**Copy your Facebook app ID and secret**

* Click `Settings / Basic` in the left sidebar
* Copy your App ID from the top of the `Basic Settings` page
* Under `App Secret` click `Show` then copy your secret
* Make sure all required fields are completed on this screen.

**Enter your Facebook app ID and secret into your Supabase project**

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/facebookauth_da6c619b33.png" alt="Facebook Auth" />
</div>


## Google Login

Openfort Auth supports Sign in with Google on the web, native Android applications and Chrome extensions.

### Overview

Setting up Twitter logins for your application consists of 3 parts:

* Create and configure a Google Project and App on the [Google Cloud Platform](https://console.cloud.google.com/home/dashboard).
* Add your Google API Key and API Secret Key to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

#### Web Configuration

##### Google pre-built configuration

1. Go to the [API Credentials page](https://console.cloud.google.com/apis/credentials).
2. Click `Create credentials` and choose `OAuth Client ID`.
3. For application type, choose `Web application`.
4. Under **Authorized redirect URLs**, enter the callback URL from the [Openfort dashboard](https://dashboard.openfort.io/players/auth/providers). Expand the Google Auth Provider section to display it.
5. When you finish configuring your credentials, you will be shown your client ID and secret. Add these to the Google Auth Provider section of the Openfort Dashboard.

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/googleauth_729cabb623.png" alt="Google Auth" />
</div>

#### Expo React Native Configuration

1. Configure OAuth credentials for your Google Cloud project in the [Credentials](https://console.cloud.google.com/apis/credentials) page of the console. When creating a new OAuth client ID, choose *Android* or *iOS* depending on the mobile operating system your app is built for.
   * For Android, use the instructions on screen to provide the SHA-1 certificate fingerprint used to sign your Android app.
     * You will have a different set of SHA-1 certificate fingerprint for testing locally and going to production. Make sure to add both to the Google Cloud Console. and add all of the Client IDs to Openfort dashboard.
   * For iOS, use the instructions on screen to provide the app Bundle ID, and App Store ID and Team ID if the app is already published on the Apple App Store.
2. Configure the [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent). This information is shown to the user when giving consent to your app. In particular, make sure you have set up links to your app's privacy policy and terms of service.
3. Finally, add the client ID from step 1 in the [Google provider on the Openfort Dashboard](https://dashboard.openfort.io/players/auth/providers), under *Client IDs*.

Note that you do not have to configure the OAuth flow in the Openfort Dashboard in order to use native sign in.


## LINE Login

Integrate LINE Login into your web app (website) to make it easier for people to create an account and log in.

### Overview

Setting up LINE login for your application consists of 3 parts:

* Create and configure a LINE Project and App on the [LINE Dashboard](https://developers.line.biz/console/).
* Add your LINE `Channel ID` and `Channel Secret` to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/Line_auth_7891fd38a0.png" alt="LINE Auth" />
</div>


## X (Twitter) Login

To enable Twitter Auth for your project, you need to set up a Twitter OAuth application and add the application credentials in the Openfort Dashboard.

### Overview

Setting up Twitter logins for your application consists of 3 parts:

* Create and configure a Twitter Project and App on the [Twitter Developer Dashboard](https://developer.twitter.com/en/portal/dashboard).
* Add your Twitter API Key and API Secret Key to your [Openfort Project](https://dashboard.openfort.io/players/auth/providers).
* Add the login code to your [Openfort JS Client App](https://github.com/openfort-xyz/openfort-js).

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/twitterauth_a9219869d5.png" alt="Twitter Auth" />
</div>

#### Configuration

1. Create Project and App:

* Click "+ Create Project", enter project name, and select use case.
* Enter a project description and app name.
* Copy and save your API Key (client\_id) and API Secret Key (client\_secret).

2. Set Up App Settings:

* Click on "App settings".
* Go to "User authentication settings" and click "Set up".

3. Configure App Permissions:

* Turn ON "Request email from users".
* Select "Web App" as the Type of App.
* Enter Callback URL, Website URL, Terms of service URL, and Privacy policy URL.

4. Set up X in Openfort:

* Go to the [Openfort dashboard](https://dashboard.openfort.io/players/auth/providers).
* Click on Twitter Enabled to turn it ON.
* Enter the Twitter Client ID and Twitter Client Secret.


import { VideoSnippet } from "@/components/VideoSnippet.tsx";
import { RapidfireDemo } from "@/components/Rapidfire/RapidfireDemo.tsx";
import { WalletInfo } from "@/components/Rapidfire/WalletInfo.tsx";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink.tsx";

## Global Wallet (Ecosystem SDK)

Openfort **Global wallets** integrate onboarding, authentication, payments, and recovery with no app or extension required. Projects use the [Ecosystem SDK](https://www.npmjs.com/package/@openfort/ecosystem-js), a TypeScript library, to bootstrap the global wallet.

:::note
Global wallets are whitelabel and allow you to own the entire developer experience. **In short, you own the *npm package* the developer installs.**
:::

We have created a *sample* global wallet called **Rapidfire ID** to showcase the Ecosystem SDK to create a global wallet. To interact with it, developers install its SDK: NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id). Check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample).

Try signing into your **Rapidfire** account:

<RapidfireDemo
  name="Connect"
  link={{
  text: "/usage-examples/wagmi-nextjs/.../wallet/WalletConnect",
  href: "https://github.com/openfort-xyz/ecosystem-sample/blob/7e4d75a456064bde2fd6e4ebb1f09487f864d12c/usage-examples/wagmi-nextjs/app/components/wallet/WalletConnect.tsx#L17",
}}
  loginCta="Sign in"
>
  <WalletInfo />
</RapidfireDemo>

#### Features

| Feature                           | Status |
| --------------------------------- | ------ |
| Authentication                    | ✅      |
| Third-party auth/signer support   | ✅      |
| Smart wallet infrastructure       | ✅      |
| Mobile Wallet Protocol compatible | ✅      |
| Themes and customization          | ✅      |

<VideoSnippet title="Rapidfire ID Demo" src="W1TTjWPJLz4" />

### Get started

Check out these popular guides to get started.

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '1rem', marginTop: '2rem' }}>
  <a href="/docs/products/cross-app-wallet/setup/react/quickstart" style={{ textDecoration: 'none', color: 'inherit' }}>
    <div style={{ padding: '1.5rem', border: '1px solid #e5e7eb', borderRadius: '8px', transition: 'all 0.2s', ':hover': { borderColor: '#3b82f6' } }}>
      <h3>Create your global wallet</h3>
      <p>Step by step guide to create your own wallet.</p>
    </div>
  </a>

  {" "}

  <a href="/docs/products/cross-app-wallet/usage/libraries" style={{ textDecoration: "none", color: "inherit" }}>
    <div
      style={{
    padding: "1.5rem",
    border: "1px solid #e5e7eb",
    borderRadius: "8px",
    transition: "all 0.2s",
    ":hover": { borderColor: "#3b82f6" },
  }}
    >
      <h3>Wallet connectors</h3>
      <p>Using a global wallet with popular wallet connectors.</p>
    </div>
  </a>

  <a href="/docs/products/cross-app-wallet/usage/web-app-wagmi" style={{ textDecoration: 'none', color: 'inherit' }}>
    <div style={{ padding: '1.5rem', border: '1px solid #e5e7eb', borderRadius: '8px', transition: 'all 0.2s', ':hover': { borderColor: '#3b82f6' } }}>
      <h3>Integrate with wagmi app</h3>
      <p>Integrate a global wallet with Wagmi.</p>
    </div>
  </a>
</div>

### Using on any wallet provider

This will internally inject a Wallet instance into your Application via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963). Modern Wallet Connection libraries will automatically detect the injected instance.

Supported wallet connection libraries include:

* [Wagmi](https://wagmi.sh/)
* [RainbowKit](https://rainbowkit.com/)
* [ConnectKit](https://docs.family.co/connectkit)

Learn more on how to get started in the [examples](/docs/products/cross-app-wallet/usage/web-app-wagmi) guide.

<HoverCardLink
  title="Global Wallet Example - Rapidfire ID"
  subtitle=""
  description="A sample ecosystem wallet that works across multiple applications."
  href="https://github.com/openfort-xyz/ecosystem-sample"
  img={{
  src: "/img/icon.svg",
  alt: "Openfort Icon",
  className: "rounded-none",
}}
  color="#fc3627"
  links={{
  sample: "https://rapidfire.sample.openfort.xyz/",
  docs: "/products/cross-app-wallet",
}}
/>


## Quickstart - 7702 Accounts

:::warning
This repository is under active development.\
Contracts are **unaudited**, and the codebase may have **breaking changes** without notice.
:::

:::note
We believe smart accounts should provide an excellent experience throughout a user's journey:

* **Effortless Onboarding**: Use WebAuthn and Passkeys with no deployment transaction required
* **Flexible Authentication**: Multiple authentication methods including EOA and WebAuthn/Passkeys
* **Fine-grained Access Control**: Session keys with customizable permissions and spending limits
* **Secure Transactions**: Built-in security features including whitelisting, function filtering, and time-based controls
* **Seamless Experience**: Full compatibility with ERC-4337 account abstraction standard
* **Gas Sponsorship**: Allow applications to pay for user transactions through session keys
* **No Vendor Lock-in**: Built on EIP-7702 and ERC-4337 standards for maximum interoperability
:::

**🟢 Live Demo**: [https://7702.openfort.io](https://7702.openfort.io)

[EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) is an upgrade (Pectra) Ethereum enhancement behaving both as a smart account and as a regular EOA, effectively creating a "hybrid" account that enables embedding EVM code into an Externally Owned Account (EOA).

Our [video blog series](https://www.youtube.com/watch?v=94VhTY-1ZsI) has more details for all of you.
Account Abstraction has many features that EOA holders can now access due to this. Account Abstraction offers sponsored gas fees as well as multiple operations batched in a single transaction plus session keys in addition to chain abstraction support with similar conveniences.

This guide walks through a basic demo that leverages ERC-4337 along with EIP-7702 so that an EOA can directly send a gasless user operation. This [video blog](https://www.youtube.com/watch?v=bE7YUrThS5k) gives information regarding the architecture of the `openfort 7702 account`.

We'll demonstrate how to build a complete smart account system that:

* Creates secure passkeys using WebAuthn
* Initializes smart accounts with non-extractable keys
* Signs and executes UserOperations seamlessly
* Implements session keys for enhanced user experience

### Installation

:::code-group
```sh [npm]
npm install viem @noble/secp256k1 ox permissionless
```

```sh [yarn]
yarn add viem @noble/secp256k1 ox permissionless
```
:::

:::steps
#### Prepares an EIP-7702 Authorization for signing

*Prepares an EIP-7702 Authorization for signing. This Action will fill the required fields of the Authorization object if they are not provided (e.g. nonce and chainId).*

**Contract:** [0xad7d8ce7b7A24f80AB107c571840851178F29650](https://sepolia.etherscan.io/address/0xad7d8ce7b7A24f80AB107c571840851178F29650)

##### `Self-execution`

```ts
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts'

const SEPOLIA_RPC = '';

const walletClient = createWalletClient({
  account,
  chain: sepolia,
  transport: http(SEPOLIA_RPC),
});

const authorization = await walletClient.prepareAuthorization({
  account: privateKeyToAccount('0x...'),
  contractAddress: '0xad7d8ce7b7A24f80AB107c571840851178F29650',
  executor: 'self', 
});
```

* Type: 'self' | undefined
* Source: [VIEM](https://viem.sh/docs/eip7702/prepareAuthorization)

##### `Ephemeral EOA`

> **What is An Ephemeral EOA:**\
> *Ephemeral key is a temporary cryptographic key created for a single use and then deleted. Unlike permanent keys, ephemeral keys are discarded after each session, making them more secure since compromised keys can't be reused.*

```ts
import { createClient } from "viem";
import { sepolia } from 'viem/chains';
import { prepareAuthorization } from "viem/actions";
import { generatePrivateKey, privateKeyToAccount, signAuthorization } from "viem/accounts";

const privateKey = generatePrivateKey();
const signer = privateKeyToAccount(privateKey);

const client = createClient({
  sepolia,
  pollingInterval: 1_000,
  transport: http()
});

const authorization = await prepareAuthorization(client, {
  account: signer.address,
  contractAddress: '0xad7d8ce7b7A24f80AB107c571840851178F29650'
});
```

#### Initialize the account with a WebAuthn owner, Session Key and guardian

```ts
function initialize(
    Key calldata _key,
    KeyReg calldata _keyData,
    Key calldata _sessionKey,
    KeyReg calldata _sessionKeyData,
    bytes memory _signature,
    bytes32 _initialGuardian
) external initializer {}
```

* Source: [OPF7702](https://github.com/openfort-xyz/openfort-7702-account/blob/3c3eecfc80d34295a9e72c749bbb9ff4b0018b48/src/core/OPF7702Recoverable.sol#L122)

##### `Creating Your First Passkey`

The adventure begins with creating a WebAuthn credential that will serve for your smart account as the primary authentication method. Your device ties to this credential as well as biometric authentication and a PIN protects that same device.

```ts
import { toHex } from "viem";
import { Bytes, WebAuthnP256 } from "ox";

// Create a WebAuthn credential using the account address as the user ID
const credential = await WebAuthnP256.createCredential({
  authenticatorSelection: {
    requireResidentKey: false,
    residentKey: "preferred",        // Store credential on device when possible
    userVerification: "required",    // Require biometric/PIN verification
  },
  user: {
    id: Bytes.from(account.address),
    name: `${account.address.slice(0, 6)}...${account.address.slice(-4)}`,
  },
});

// Store the credential ID for future authentication
const credentialId = credential.id;

const x = toHex(credential.publicKey.x, { size: 32 });
const y = toHex(credential.publicKey.y, { size: 32 });
```

* A unique key pair that is bound to their device is then created when this process prompts authentication by the user through Face ID, Touch ID, Windows Hello, etc. The private key remains within secure hardware. Smart account initialization returns back the public key.

##### `CallData`

With the WebAuthn credential now created, a smart account recognizing this passkey as its primary signer can be initialized:

* Prepare Key Data

```ts
import { zeroAddress, toHex, keccak256, encodeFunctionData } from "viem";

export enum KeyType {
  EOA = 0,
  WEBAUTHN = 1,
  P256 = 2,
  P256_NON_EXTRACTABLE = 3,
}

const key = {                               
  pubKey: {                         
    x: toHex(x),                   
    y: toHex(y),                   
  },
  eoaAddress: zeroAddress,         
  keyType: KeyType.WEBAUTHN,       
} as const;
```

* Prepare Token Spend

```ts
const spendTokenInfo = {
  token: zeroAddress,             
  limit: 0n,
} as const;
```

* Prepare Key Registration Data

```ts
const keyReg = {
  validUntil: 0n,
  validAfter: 0n,
  limit: 0n,
  whitelisting: false,
  contractAddress: zeroAddress,
  spendTokenInfo: spendTokenInfo,
  allowedSelectors: ['0xdeedbeff'],
  ethLimit: 0n
} as const;

const initialGuardian = keccak256('address');
```

* Prepare Session Key Registration Data (Optional)

```ts
const sessionKey = {                               
  pubKey: {                         
    x: toHex(x), // if not register sessionKey add bytes32(0)                   
    y: toHex(y), // if not register sessionKey add bytes32(0)                   
  },
  eoaAddress: zeroAddress, // if not register sessionKey add zeroAddress         
  keyType: KeyType.P256_NON_EXTRACTABLE,       
} as const;

const spendTokenInfo = {
  token: usdcAddress,             
  limit: spending_limits,
} as const;

const sessionKeyReg = {
  validUntil: unixTime,
  validAfter: unixTime,
  limit: limits,
  whitelisting: true,
  contractAddress: address,
  spendTokenInfo: spendTokenInfo,
  allowedSelectors: [approve_selector, transfer_selector, swap_selector],
  ethLimit: eth_limits
} as const;
```

* Call Data (If Sponsored use with `userOperation`)

```ts
// Prepare the initialization call data
const callData = encodeFunctionData({
  abi: accountABI,
  functionName: "initialize",
  args: [
    key,
    keyReg,
    sessionKey,
    sessionKeyReg,                    
    SIGNATURE_EIP712,  // sign with EOA/EPHEMERAL EOA `function getDigestToInit`
    initialGuardian
  ]
});

// Create the user operation with EIP-7702 authorization if EPHEMERAL EOA
const userOperation = await walletClient.prepareUserOperation({
  callData,
  authorization: signedAuthorization,  // EIP-7702 authorization signature
});
```

* An EOA can temporarily act as a smart contract because EIP-7702 authorization exists so it enables the initialization process. After execution of this UserOperation, your smart account is ready for WebAuthn-based transactions.

#### Register Session Key P256

```js
function registerKey(Key calldata _key, KeyReg calldata _keyData) public {}
```

* Source: [OPF7702](https://github.com/openfort-xyz/openfort-7702-account/blob/3c3eecfc80d34295a9e72c749bbb9ff4b0018b48/src/core/KeysManager.sol#L71)

##### `Creating a Session Key`

* Session keys are additionally non-extractable P256 keys that exist. They are created through usage of the WebCrypto API and are stored in a local way:

```ts
import { WebCryptoP256 } from "ox";

// Generate a new P256 key pair for the session
const keyPair = await WebCryptoP256.createKeyPair();
const publicKey = await WebCryptoP256.getPublicKey({ 
  publicKey: keyPair.publicKey 
});

// Store the key pair securely (e.g., in IndexedDB)
await storeSessionKey(keyPair);
```

* WebAuthn is great for security, but nobody wants to scan their fingerprint for every little action. Session keys fix that: they're short-lived "spare keys" with limited powers, so you can breeze through everyday tasks without constant biometric check-ins.

##### `Registering the Session Key`

The session key must be registered with the smart account because it defines its permissions along with validity:

* Prepare Key Data

```ts
const key = {                               
  pubKey: {                         
    x: toHex(publicKey.x),         // The P256 public key x coordinate
    y: toHex(publicKey.y),         // The P256 public key y coordinate           
  },
  eoaAddress: zeroAddress,         
  keyType: KeyType.P256_NON_EXTRACTABLE,       
} as const;

const spendTokenInfo = {
  token: TOKEN_ADDRESS,             
  limit: SPEND_LIMIT,
} as const;
```

* Prepare Key Registration Data

```ts
const keyReg = {
  validUntil: VALID_UNTIL,
  validAfter: VALID_AFTER,
  limit: ACTIONS_LIMIT,
  whitelisting: true,
  contractAddress: CONTRACT_ADDRESS,
  spendTokenInfo: spendTokenInfo,
  allowedSelectors: [ALLOW_SELECTORS],
  ethLimit: ETH_SPEND_LIMIT
} as const;
```

* Call Data (If Sponsored use with `userOperation`)

```ts
const callData = encodeFunctionData({
  abi: accountABI,
  functionName: 'registerSessionKey',
  args: [
    key,
    keyReg
  ]
});

// This registration requires WebAuthn approval
const userOperation = await walletClient.prepareUserOperation({
  callData,
  signature: webAuthnStubSignature,
});

// Sign with WebAuthn (one-time approval for session key)
const webauthnData = await WebAuthnP256.sign({
  challenge: getUserOperationHash(userOperation),
  credentialId,
  rpId: window.location.hostname,
  userVerification: "required",
});
```

#### Executing Transactions with WebAuthn

Let's show the time when we mint some ERC-20 tokens. First, a UserOperation is prepared by us with a placeholder for its signature. Then, the actual WebAuthn signature acts in its place:

* `Preparing the Transaction`

```ts
// Encode the mint function call
const data = encodeFunctionData({
  abi: erc20ABI,
  functionName: "mint",
  args: [
    walletClient.account.address,
    parseEther("10"),  // Mint 10 tokens
  ],
});

// Prepare UserOperation with stub signature
const userOperation = await walletClient.prepareUserOperation({
  calls: [
    {
      to: erc20Address,
      data,
    },
  ],
  signature: webAuthnStubSignature,  // Placeholder signature
});
```

The actual signature is now generated using the WebAuthn credential:

```ts
// Get the UserOperation hash that needs to be signed
const userOperationHash = getUserOperationHash(userOperation);

// Sign with WebAuthn - this triggers biometric authentication
const webauthnData = await WebAuthnP256.sign({
  challenge: userOperationHash,
  credentialId,                      // The credential we created earlier
  rpId: window.location.hostname,    // Relying party identifier
  userVerification: "required",      // Require user verification
});

// Replace stub signature with the actual WebAuthn signature
userOperation.signature = encodeWebAuthnSignature(webauthnData);

// Send to bundler for execution
await bundlerClient.sendUserOperation(userOperation);
```

* The user experiences a familiar biometric prompt like Face ID, fingerprint, etc., so once they authenticate, someone signs then submits the transaction.

#### Using Session Keys for Transactions

* After setup, your session keys can authorize transactions on their own—no fingerprint or face scan needed:

##### `Prepare CallData`

* Call Data (If Sponsored use with `userOperation`)

```ts
import { WebCryptoP256 } from "ox";

// Prepare the transaction as before
const userOperation = await walletClient.prepareUserOperation({
  calls: [
    {
      to: erc20Address,
      data: encodeFunctionData({
        abi: erc20ABI,
        functionName: "mint",
        args: [walletClient.account.address, parseEther("10")],
      }),
    },
  ],
  signature: P256Signature,
});

// Sign with the session key (no user interaction required)
const { r, s } = await WebCryptoP256.sign({
  privateKey: sessionKey.privateKey,
  payload: getUserOperationHash(userOperation),
});

// Format and attach the signature
userOperation.signature = encodeP256Signature({ r, s });

// Submit the transaction
await bundlerClient.sendUserOperation(userOperation);
```
:::

### Conclusion

WebAuthn with P256 signatures marks a large advance with regard to Web3 security, as well as user experience. Smart accounts that are more secure and even more user-friendly than customary wallets, can be built through leveraging familiar authentication methods and also eliminating private key exposure.

Adapting to different security contexts, a system results from combining WebAuthn for high-security operations and session keys for routine transactions requiring strong authentication for sensitive actions enabling frictionless interactions for everyday use.


import { MultiOptionDisplay } from '@/components/MCP/MultiOptionDisplay';
import { AddToCursor } from '@/components/MCP/AddToCursor';
import { CopyPrompt } from '@/components/MCP/CopyPrompt';
import Prompt1 from '@/components/MCP/prompt1.mdx?raw';
import Rules from '@/components/MCP/rules.mdx?raw';

## AI Tooling Quickstart

Get started using Openfort's AI tooling to build your app faster than ever.

#### Steps

1. Install Openfort's MCP server.
2. Add rules for the LLMs.
3. Create a new project.
4. Debug common issues.
5. Discover all the capabilities.

### 1. Install Openfort's MCP server

This will allow your AI Assistant to interact with Openfort's tools on your behalf to create projects and manage them.

Ensure you have the following prerequisites:

* `Node.js` - Installation guide [here](https://nodejs.org/en/download)
* An `Openfort account` - Create one [here](https://dashboard.openfort.io/)

Now, add it to your code editor. Based on your preferred tool, follow the instructions below:

<MultiOptionDisplay
  options={[
  { id: 'cursor', label: 'Cursor' },
  { id: 'windsurf', label: 'Windsurf' },
  { id: 'vscode', label: 'VS Code' },
  { id: 'claude', label: 'Claude Desktop' },
]}
/>

<span id="cursor" className="hidden [&>*]:mb-6!">
  To integrate our MCP Server with [Cursor](https://docs.cursor.com/context/mcp) you can either:

  ##### One-click installation

  <AddToCursor />

  ##### Edit the `~/.cursor/mcp.json`

  You can look it up on your system or find it under the `Tools & Integrations` tab in your `Cursor Settings`. Fill it with the following content:

  ```json
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```

  Then you should see the Openfort MCP server listed on your `Tools & Integrations` tab without the need to restart. The authentication will trigger automatically.
</span>

<span id="windsurf" className="hidden [&>*]:mb-6!">
  For integration with [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#custom-mcp-server-sse), replace the contents of the `~/.codeium/windsurf/mcp_config.json` file with the following. It can be located at:

  `Windsurf Settings > Cascade > Plugins (MCP Servers) > View Raw Config`

  :::code-group
  ```json [MacOS/Linux]
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ],
        "disabled": false
      }
    }
  }
  ```

  ```json [Windows]
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "cmd",
        "args": [
          "/c",
          "npx",
          "mcp-remote",
          "https://mcp.openfort.io/sse"
          ],
        "disabled": false
      }
    }
  }
  ```
  :::
</span>

<span id="vscode" className="hidden [&>*]:mb-6!">
  To integrate an MCP Server into [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for use with GitHub Copilot, you should edit the `.vscode/mcp.json` file or run the `MCP: Open User Configuration` command which opens the file to add the following content:

  ```json
  {
    "servers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```
</span>

<span id="claude" className="hidden [&>*]:mb-6!">
  To add our MCP Server to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user), click on `Edit Config` in the `Developer` tab under `Settings` to automatically create a file at:

  * macOS: `~/Library/Application  Support/Claude/claude_desktop_config.json`
  * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

  Once created, fill it with the following content:

  ```json
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```

  You will need to restart Claude Desktop after modifying the configuration file. Also, if you freshly installed Node.js you may need to reboot your computer too.
</span>

### 2. Add rules for the LLMs

LLMs tend to forget about the availability of tools and can make some pathological mistakes. Therefore, it's a good idea to include rules to remind them about this. Here's how to set them up.

<MultiOptionDisplay
  options={[
{ id: 'cursor-rules', label: 'Cursor' },
{ id: 'windsurf-rules', label: 'Windsurf' },
{ id: 'other-rules', label: 'Other' },
]}
/>

<span id="cursor-rules" className="hidden [&>*]:mb-6!">
  Add these rules to the configuration at `Rules & Memories > User Rules > Add Rule`.
  For project-specific rules, you can add them at `.cursor/rules/openfort.md`

  <CopyPrompt title="Copy rules for Cursor" content={Rules} />
</span>

<span id="windsurf-rules" className="hidden [&>*]:mb-6!">
  Add these rules to the root folder of your project at `.windsurf/rules/openfort.md`.
  For global rules, you can add them at:

  `Windsurf Settings > Cascade > Customizations > Cascade Rules > + Global`

  <CopyPrompt title="Copy rules for Windsurf" content={Rules} />
</span>

<span id="other-rules" className="hidden [&>*]:mb-6!">
  Copy these rules and add them to any AI assistant you use.

  <CopyPrompt title="Copy rules for any AI Assistant" content={Rules} />
</span>

### 3. Create a new project

Now create a new project in your editor and type up a prompt to the LLM to scaffold it for you. When needed, the LLM will automatically call the [available tools](https://www.openfort.io/docs/configuration/ai-tooling/mcp-server/tools) on Openfort's MCP Server, enhancing your developer experience. Here's an example prompt you can try:

<CopyPrompt title="An Openfortkit App" content={Prompt1} description="This is a simple Openfortkit app that uses the OpenfortKitButton to onboard users and create new wallets. It also sets up a policy to sponsor transactions and a contract to mint." />

### 4. Debug Common Issues

Here are some common issues you might encounter and how to resolve them.

:::details[General Errors]
After the agent finishes creating a project, it may still throw errors, even with extended context. This is especially common for complex prompts or large applications.

> Don’t expect the AI to flawlessly generate entire applications in a single prompt without any issues.

To resolve these errors, fix them manually or ask the AI for help. Iteration is normal, review the output, make corrections, and continue prompting as needed.
:::

***

:::details[Loop When Creating a Policy]
Occasionally, the AI agent may get stuck in a loop while creating a policy. The policy is successfully created, but the agent repeatedly attempts to update it with the same values.

> The cause is unknown, and the effect is harmless.

To fix this, simply cancel the generation and prompt the agent to continue with the next step.
:::

***

:::details[npm Error: `Missing script: "dev"`]
If the AI agent fails to start the project using `npm run dev`, it’s often because it created the project in a subfolder and didn’t change into that directory before running the command.

> Manually navigate to the subfolder and run the project again.
:::

***

:::details[No Permission to Edit the `.env` File]
When the AI agent fails to edit or create a `.env` file with your project keys, it’s usually due to insufficient file permissions.

> In Cursor, add a `.cursorignore` file with `!.env` to explicitly allow the AI to edit the `.env` file.
>
> For other editors or environments, follow an equivalent approach to ensure the file is not ignored.
:::

### 5. Discover all the capabilities

For more information on the available tools and how to use them, check out the [MCP Server documentation](https://www.openfort.io/docs/configuration/ai-tooling/mcp-server/tools).


import { OpenfortKitButton } from "@/components/Openfortkit/OpenfortKitButton";
import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { CogIcon } from "lucide-react";

## Embedded Wallet

{/* <OpenfortKitButton /> */}

### Choose Your Platform

<HoverCardLayout className="grid-cols-2!">
  <HoverCardLink
    description="React SDK for web applications."
    href="/products/embedded-wallet/react/kit"
    title="React"
    subtitle="Web - @openfort/openfort-kit"
    img={{
    src: "/img/icons/react-icon.svg",
    alt: "React",
  }}
    color="#61DAFB"
  />

  <HoverCardLink
    description="React SDK for mobile applications."
    href="/products/embedded-wallet/react-native"
    title="React Native"
    subtitle="Mobile - @openfort/react-native"
    img={{
    src: "/img/icons/libraries/react-native-icon.svg",
    alt: "React",
  }}
    color="#61DAFB"
  />

  <HoverCardLink
    description="For applications that need more customization."
    href="/products/embedded-wallet/javascript"
    title="Vanilla JavaScript"
    subtitle="Core SDK - @openfort/openfort-js"
    img={{
    src: "/img/icons/javascript-icon.svg",
    alt: "JavaScript Icon",
  }}
    color="#F7DF1E"
  />

  <HoverCardLink
    description="For game development with Unity engine."
    href="/products/embedded-wallet/unity"
    title="Unity"
    subtitle="Game Development"
    img={{
    src: "/img/icons/libraries/unity.svg",
    alt: "Unity Icon",
    invertOnDark: true,
  }}
    color="#aaa"
  />
</HoverCardLayout>

### What is an Embedded Wallet?

Embedded wallets provide a seamless blockchain experience by abstracting away the complexity of wallet management. Users can interact with your application without needing to understand private keys, seed phrases, or blockchain concepts.

#### Key Features

* **Seamless Authentication**: Users sign in with familiar methods like email, social logins, or third-party auth providers
* **No Seed Phrases**: Secure key management without burdening users with recovery phrases
* **Cross-Platform**: Consistent wallet experience across web, mobile, and game engines
* **Smart Wallet Support**: Built-in support for account abstraction and gasless transactions
* **Recovery Options**: Multiple recovery methods to ensure users never lose access


## User Session (JWT/Authorization)

### Getting a user's access token from a request

When your app frontend sends a request to your server, you should include the current user's access token in the Authorization header of the request. This allows your backend to securely identify the requesting user and gate API routes based on their authentication status, their user ID, and more.

:::info
This guide assumes you have already configured your frontend to including users' access tokens in requests to your server. If this is not the case, please begin with the [frontend authorization guide](/docs/products/embedded-wallet/javascript/auth/user-sessions).
:::

When your server receives a request, the location of the user's access token depends on whether your app uses local storage (the default) or cookies to manage user sessions:

* If using **local storage** to store a user's session, the access token will be passed in the Authorization header of the request.
* If using **cookies** to store a user's session, the access token will be passed in the openfort-token cookie on the request.

For example, in [NextJS](https://nextjs.org/), you might extract the auth token from a `NextApiRequest` as follows:

:::code-group
```ts [Using Local Storage]
const accessToken = req.headers.authorization.replace('Bearer ', '');
```

```ts [Using Cookies]
const accessToken = req.cookies['openfort-token'];
```
:::

### Verifying the user's access token

Once you've obtained the user's access token from a request, you should verify the token against Openfort's verification key for your app to confirm that the token was issued by Openfort and the user referenced by the player Id in the token is truly authenticated.

The access token is a standard ES256 JWT and the verification key is a standard Ed25519 public key. You can verify the access token against the public key using the official supported libraries library or using a third-party library for managing tokens.

#### When using Openfort auth

:::code-group
```ts [Node.js]
import Openfort from "@openfort/openfort-node";
const openfort = new Openfort(process.env.OPENFORT_SK);

const authSession = openfort.iam.verifyAuthToken("USER_AUTH_TOKEN");
```

```csharp [.NET]
using Openfort.SDK.Model;

class Program
{
  static async Task Main()
  {
    var client = new Openfort.SDK.OpenfortClient("sk_test_...");
    var authSession = await client.Iam.VerifyAuthToken("USER_AUTH_TOKEN");
  }
}
```
:::

#### When using a third-party auth

When using a third-party auth provider, you can either verify the token using the provider's SDK or use Openfort's SDK to verify the token.

```ts [Node.js]
import Openfort from "@openfort/openfort-node";
const openfort = new Openfort(process.env.OPENFORT_SK);

const authSession = openfort.iam.verifyOAuthToken({
      provider: 'firebase', // one of "google" | "twitter" | "facebook" | "discord" | "epic_games" | "accelbyte" | "firebase" | "lootlocker" | "playfab" | "supabase" | "custom" | "oidc";
      token: "USER_AUTH_TOKEN",
      tokenType: 'idToken', // either "idToken" | "customToken"
    });
```


import { HoverCardLink } from "@/components/HoverCard/HoverCardLink";
import { HoverCardLayout } from "@/components/HoverCard/HoverCardLayout";
import { Database, DatabaseZap, ShieldCheck, Wallet2 } from "lucide-react";

## Using Openfort from your server

Openfort's client-side SDKs, like [`@openfort/openfort-js`](https://www.npmjs.com/package/@openfort/openfort-js), allow you to securely authenticate your users, connect their wallets, and create embedded wallets for them in your application frontend.

In addition to these SDKs, you can also use **Openfort from your server** to secure and manage your application. See the guides below for some common flows.

### Get started

<HoverCardLayout>
  <HoverCardLink title="Verification" subtitle="Access token verification." description="Verify the authenticity of a user's access token." href="/products/server/access-token" icon={ShieldCheck} color="#10B981" />

  <HoverCardLink title="Backend wallets" subtitle="Manage on-chain operations." description="Create backend wallets for your application to manage on-chain operations." href="/products/server/wallet" icon={DatabaseZap} color="#61DAFB" />

  <HoverCardLink title="Pregenerate wallets" subtitle="For your users." description="Generate wallets for users before they sign up." href="/products/server/pregenerate-wallets" icon={Wallet2} color="#F59E0B" />
</HoverCardLayout>

### SDKs and API reference

<HoverCardLayout>
  <HoverCardLink
    title="Node.js"
    subtitle="Javascript"
    description="NodeJS SDK for interacting with Openfort's infrastructure."
    href="https://openfort.apidocumentation.com"
    img={{
    src: "/img/icons/libraries/node.svg",
    alt: "Node.js Icon",
  }}
    color="#fc3627"
    links={{
    github: "https://github.com/openfort-xyz/openfort-node"
  }}
  />

  <HoverCardLink
    title=".NET"
    subtitle="C#"
    description="C# SDK for interacting with Openfort's infrastructure."
    href="https://openfort.apidocumentation.com"
    img={{
    src: "/img/icons/libraries/c-sharp-icon.svg",
    alt: "Node.js Icon",
  }}
    color="#fad323"
    links={{
    github: "https://github.com/openfort-xyz/openfort-csharp"
  }}
  />

  <HoverCardLink title="Api reference" subtitle="REST API" description="Comprehensive API reference for interacting with Openfort's infrastructure." href="https://openfort.apidocumentation.com" icon={Database} color="#4B5563" />
</HoverCardLayout>


## Provider migration \[Migrate users from one Auth provider to another using Openfort's migration tool]

This tool allows you to link users from one authentication provider to another, ensuring a smooth transition without losing any user data.

In this guide we will be creating a migration from **OIDC provider** with google oauth flow to **openfort Google provider**.
This is useful if you want to migrate users from a custom OIDC provider to Openfort's Google provider.

### Creating a migration

1. Enable both your source and destination providers in the Openfort dashboard.
   You can do this in the [Providers](https://dashboard.openfort.io/players/auth/providers) section of your Openfort dashboard.

2. Start by going to the [Migration page](https://dashboard.openfort.io/players/auth/migrations) in your Openfort dashboard and create a new one.

3. Select the source destination, and add the matching criteria for the users you want to migrate.

   <div align="center">
     <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/provider_migration_1_f3e2c45fa7.png" alt="migration-1" style={{ border: '1px solid #ccc' }} />
   </div>

4. Do the same for the destination provider.

5. Click on **Create migration**.

6. Start the migration by clicking on the **Start migration** button, next to "Ready to start".

   <div align="center">
     <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/provider_migration_2_014ffe463d.png" alt="migration-2" />
   </div>

7. That is it! Now when a user logs in with **openfort Google provider**, they will be automatically linked to their OIDC account.

When all users are migrated, you can mark the migration as complete by clicking on the **Mark as complete** button.


## Pregenerating an embedded wallet

You can pregenerate non-custodial wallet associated with a given account, like an email address or social login, without requiring the user to login. You can even send assets to the wallet before the user logs in to your app for the first time. Once the user associated with the account logs in, they will be able to access the pregenerated wallet and any assets sent to them. To pregenerate wallets, use one of the supported backend SDKs:

A user can easily claim their pregenerated wallet simply by logging into your app with one of its linked accounts.

:::code-group
```ts [Node.js]
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const notifications = await openfort.iam.createAuthPlayer(
{ 
  thirdPartyUserId: "user id",
  thirdPartyProvider: 'provider name', // Id of the provider of the user
  preGenerateEmbeddedAccount: true
  chainId: 4337,
  metadata: {
    name: "Jaume"
    }
},
{
  shieldAuthProvider: '', // ShieldAuthProvider.OPENFORT or ShieldAuthProvider.CUSTOM
  apiKey: '', // Shield publishable key
  apiSecret: '', // Shield secret key
  encryptionPart: '' // Shield encryption share
})
```

```csharp [.NET]
using Openfort.SDK;
using Openfort.SDK.Model;
const openfort = new OpenfortClient(YOUR_SECRET_KEY);

const notifications = await openfort.Iam.CreateAuthPlayer(
  new CreateAuthPlayerRequest(
    ThirdPartyUserId = "user id",
    ThirdPartyProvider = 'provider name', // Id of the provider of the user
    PreGenerateEmbeddedAccount = true,
    ChainId = 4337, 
  ),
  new PreGenerateEmbeddedAccountsConfiguration(
    ShieldAuthProvider = ShieldAuthProvider.OPENFORT, // ShieldAuthProvider.OPENFORT or ShieldAuthProvider.CUSTOM
    ApiKey = '', // Shield publishable
    ApiSecret = '', // Shield secret key
    EncryptionPart = '' // Shield encryption share
  )
);
```
:::

In the body of the request:

* `thirdPartyUserId`: the user's account id.
* `thirdPartyProvider`: the provider used: custom, supabase, oidc, etc.
* `preGenerateEmbeddedAccount`: boolean with the value **true**.

A successful response will include the new user object along with their user's ID (`playerID`), as shown in the Response tab above.

```json [Response]
{
"id": "pla_ff54b031-a878-4ca2-9cf5-ae190f921e9b",
"object": "player",
"createdAt": 1691658234,
"linkedAccounts": [
  {
    "provider": "email",
    "email": "jaume@openfort.io",
    "disabled": false,
    "updatedAt": 1691658234
  }
]
}
```


## Server Environment Setup

This guide will help you set up your server environment to work with Openfort, including getting your API keys and configuring the necessary SDKs for backend operations.

### Get your API keys

To start, go to the [Openfort Dashboard](https://dashboard.openfort.io) and select your desired project from the dropdown at the top. Then, navigate to the Developers page > API Keys tab for your app. Then grab your secret key.

:::warning
Your app secret is a sensitive value that gives you permission to manage Openfort from your server. Do not expose it outside of your backend server.
:::

Once you've retrieved your API keys, you can begin interacting with Openfort's API in one of two ways: using the server-side SDKs, or querying Openfort's REST API directly.

### Server SDKs

These libraries include helpful utilities around verifying access tokens issued by Openfort and interacting with Openfort's API to query and import users, create wallets, verify webhooks, and more.

You can visit the [SDK reference documentation](https://openfort.apidocumentation.com) to learn more about the available SDKs and how to use them in your server-side application.

:::code-group
```ts [Node.js]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);
```

```csharp [.NET]
using Openfort.SDK;
using Openfort.SDK.Model;
const openfort = new OpenfortClient(YOUR_SECRET_KEY);
```
:::

### Using the REST API

You can visit the [API reference documentation](https://openfort.apidocumentation.com) to learn more.

For example, in a JavaScript fetch request, your headers should look like:

```js
headers: {
    'Authorization': `Bearer sk_test_...`,
}
```


import { MultiOptionDisplay } from '@/components/MCP/MultiOptionDisplay';
import { CopyPrompt } from '@/components/MCP/CopyPrompt';
import Prompt1 from '@/components/MCP/prompt1.mdx?raw';
import Rules from '@/components/MCP/rules.mdx?raw';

## Prompts & Examples

Once everything is set up, you can start using your AI assistant as usual. It will now have access to the tools provided by Openfort's MCP Server and will call them when needed.

* It can create projects without the need for you to set them up in the dashboard.
* It can automatically retrieve keys from your project and store them safely.
* It can set up policies, contracts, and create users and accounts.
* It can fetch real-time data from your project.
* It can scaffold your project faster than ever.
* It can get context from the latest version of Openfort's documentation.

If you need further inspiration, here are some considerations and use cases.

### Rules

LLMs tend to forget about the availability of tools and can make some pathological mistakes. Therefore, it's a good idea to include rules to remind them about this. Here's how to set them up.

<MultiOptionDisplay
  options={[
{ id: 'cursor', label: 'Cursor' },
{ id: 'windsurf', label: 'Windsurf' },
{ id: 'other', label: 'Other' },
]}
/>

<span id="cursor" className="hidden [&>*]:mb-6!">
  Add these rules to the configuration at `Rules & Memories > User Rules > Add Rule`.
  For project-specific rules, you can add them at `.cursor/rules/openfort.md`

  <CopyPrompt title="Copy rules for Cursor" content={Rules} />
</span>

<span id="windsurf" className="hidden [&>*]:mb-6!">
  Add these rules to the root folder of your project at `.windsurf/rules/openfort.md`.
  For global rules, you can add them at:

  `Windsurf Settings > Cascade > Customizations > Cascade Rules > + Global`

  <CopyPrompt title="Copy rules for Windsurf" content={Rules} />
</span>

<span id="other" className="hidden [&>*]:mb-6!">
  Copy these rules and add them to any AI assistant you use.

  <CopyPrompt title="Copy rules for any AI Assistant" content={Rules} />
</span>

### Prompts

Here are some example prompts to guide your AI assistant in creating projects with Openfort’s features. Copy and paste them directly into the chat to try them out.

<CopyPrompt title="An Openfortkit App" content={Prompt1} description="This is a simple Openfortkit app that uses the OpenfortKitButton to onboard users and create new wallets. It also sets up a policy to sponsor transactions and a contract to mint." />

### Common Issues

:::details[General Errors]
After the agent finishes creating a project, it may still throw errors, even with extended context. This is especially common for complex prompts or large applications.

> Don’t expect the AI to flawlessly generate entire applications in a single prompt without any issues.

To resolve these errors, fix them manually or ask the AI for help. Iteration is normal, review the output, make corrections, and continue prompting as needed.
:::

***

:::details[Loop When Creating a Policy]
Occasionally, the AI agent may get stuck in a loop while creating a policy. The policy is successfully created, but the agent repeatedly attempts to update it with the same values.

> The cause is unknown, and the effect is harmless.

To fix this, simply cancel the generation and prompt the agent to continue with the next step.
:::

***

:::details[npm Error: `Missing script: "dev"`]
If the AI agent fails to start the project using `npm run dev`, it’s often because it created the project in a subfolder and didn’t change into that directory before running the command.

> Manually navigate to the subfolder and run the project again.
:::

***

:::details[No Permission to Edit the `.env` File]
When the AI agent fails to edit or create a `.env` file with your project keys, it’s usually due to insufficient file permissions.

> In Cursor, add a `.cursorignore` file with `!.env` to explicitly allow the AI to edit the `.env` file.
>
> For other editors or environments, follow an equivalent approach to ensure the file is not ignored.
:::


import { MultiOptionDisplay } from "@/components/MCP/MultiOptionDisplay";
import { AddToCursor } from "@/components/MCP/AddToCursor";

## MCP Server

Openfort’s MCP Server is a plug-and-play solution that enhances AI assistants by enabling them to create projects, manage configurations, and query data automatically when building applications on Openfort's infrastructure.

### What's an MCP Server?

AI agents in AI-powered IDEs excel at reasoning and generating high-quality answers. However, they usually stall when it comes to building real-world applications. Their limitations arise from being isolated from real-time data and actionable tools.

<u>**Model Context Protocol**</u> (MCP) provides a universal and open [standard](https://modelcontextprotocol.io/introduction)
for connecting AI systems to live data sources, callable functions, and richer context.

In a client-server architecture, the AI agent (MCP Client) in your code editor connects to an MCP Server. This connection enables real-time context awareness and seamless integration with external tools (set up by the server provider), allowing the language model to invoke them as needed.

### Quickstart

Openfort's MCP Server can be easily plugged into your code editor. The only requirement is to have a working Openfort account; you can create one [here](https://dashboard.openfort.io/). You will also need [Node.js](https://nodejs.org/en) installed on your computer. To verify you have Node, open the command line on your computer and run:

```bash
node --version
```

If Node.js is not installed, you can follow the [installation guide](https://nodejs.org/en/download).

<MultiOptionDisplay
  options={[
  { id: 'cursor', label: 'Cursor' },
  { id: 'windsurf', label: 'Windsurf' },
  { id: 'vscode', label: 'VS Code' },
  { id: 'claude', label: 'Claude Desktop' },
]}
/>

<span id="cursor" className="hidden [&>*]:mb-6!">
  To integrate our MCP Server with [Cursor](https://docs.cursor.com/context/mcp) you can either:

  ##### One-click installation

  <AddToCursor />

  ##### Edit the `~/.cursor/mcp.json`

  You can look it up on your system or find it under the `Tools & Integrations` tab in your `Cursor Settings`. Fill it with the following content:

  ```json
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```

  Then you should see the Openfort MCP server listed on your `Tools & Integrations` tab without the need to restart. The authentication will trigger automatically.
</span>

<span id="windsurf" className="hidden [&>*]:mb-6!">
  For integration with [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#custom-mcp-server-sse), replace the contents of the `~/.codeium/windsurf/mcp_config.json` file with the following. It can be located at:

  `Windsurf Settings > Cascade > Plugins (MCP Servers) > View Raw Config`

  :::code-group
  ```json [MacOS/Linux]
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ],
        "disabled": false
      }
    }
  }
  ```

  ```json [Windows]
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "cmd",
        "args": [
          "/c",
          "npx",
          "mcp-remote",
          "https://mcp.openfort.io/sse"
          ],
        "disabled": false
      }
    }
  }
  ```
  :::
</span>

<span id="vscode" className="hidden [&>*]:mb-6!">
  To integrate an MCP Server into [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for use with GitHub Copilot, you should edit the `.vscode/mcp.json` file or run the `MCP: Open User Configuration` command which opens the file to add the following content:

  ```json
  {
    "servers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```
</span>

<span id="claude" className="hidden [&>*]:mb-6!">
  To add our MCP Server to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user), click on `Edit Config` in the `Developer` tab under `Settings` to automatically create a file at:

  * macOS: `~/Library/Application  Support/Claude/claude_desktop_config.json`
  * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

  Once created, fill it with the following content:

  ```json
  {
    "mcpServers": {
      "openfort-mcp": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.openfort.io/sse"
        ]
      }
    }
  }
  ```

  You will need to restart Claude Desktop after modifying the configuration file. Also, if you freshly installed Node.js you may need to reboot your computer too.
</span>

### Important note

Once it's been set up, you will be asked to authenticate with your Openfort account.

:::warning
By authenticating, you grant the LLM permission to act on your behalf within Openfort's infrastructure. By default, you will be prompted to approve or deny each tool execution.
:::

From here, the LLM will automatically invoke the [available tools](https://www.openfort.io/docs/configuration/ai-tooling/mcp-server/tools) from Openfort's MCP Server on demand, helping your developer experience. Tool updates will sync automatically.


## Available Tools

Our MCP Server provides three main tool categories to enhance your coding experience:

1. Context – Fetch real‑time documentation and code snippets to scaffold your project.
2. Management – Create and initialize new projects effortlessly.
3. Project – Control all the details within a specific project.

### Context

**Documentation**

* `search-documentation`: Searches a given phrase in the latest live version of [Openfort's documentation](https://www.openfort.io/docs).

**Initialization**

* `create-openfortkit-app`: Provides a guide to the LLM on how to create a React + Vite app using [Openfort Kit](https://www.openfort.io/docs/products/embedded-wallet/react/kit).

### Management

**Projects**

* `list-projects`: List all your projects.
* `get-project`: Get details of a specific project.
* `create-project`: Create a new project.
* `select-project`: Sets a project as active. Subsequent project-specific actions will apply to the selected project.
* `show-selected-project`: Show currently selected project by the Agent.
* `deselect-project`: Deselect the project.

**Keys**

* `get-publishable-keys`: Get public project keys.
* `get-secret-keys`: Get secret project keys.
* `get-shield-publishable-key`: Get shield public key.
* `get-shield-secret-key`: Get shield private key.
* `create-publishable-key`: Create new public key.
* `create-secret-key`: Create new secret key.
* `create-shield-keys`: Create public, private, and encryption shield keys.

:::danger
Do not expose the encryption share returned by the `create-shield-keys` to the client side of your application. The MCP explicitly states to the LLM that the encryption share should never be exposed but it's not deterministic.
:::

### Project

**Policies**

* `list-policies`: Retrieves a list of all policies associated with the selected project.
* `create-policy`: Creates a new policy for your project.
* `get-policy`: Fetches details of a specific policy.
* `update-policy`: Updates an existing policy with new information.
* `delete-policy`: Removes a specified policy from your project.
* `disable-policy`: Disables a policy without deleting it.
* `enable-policy`: Re-enables a previously disabled policy.
* `list-policy-rules`: Lists all rules associated with a specific policy.
* `create-policy-rule`: Adds a new rule to a specified policy.
* `update-policy-rule`: Modifies an existing rule within a policy.
* `delete-policy-rule`: Deletes a specific rule from a policy.

**Contracts**

* `create-contract`: Creates a new contract for the selected project.
* `get-contract`: Retrieves details of a specific contract.
* `list-contracts`: Lists all contracts associated with the selected project.
* `update-contract`: Updates the details of an existing contract.
* `delete-contract`: Removes a specified contract from your project.

**Users**

* `create-user`: Creates a new user in the project.
* `get-user`: Get detailed information about a specific user in the project.
* `list-users`: Get the users in the project.
* `update-user`: Update an existing user's information.
* `delete-user`: Delete a user from the project.

**Accounts**

* `create-account`: Creates a new blockchain account for the provided player. If no player is provided, a new one will be created.
* `get-account`: Get detailed information about a specific account in the project.
* `list-accounts`: Get the accounts in the project with optional filtering.

**Transactions**

* `list-transactions`: Lists all transactions associated with the selected project.
* `get-transaction`: Retrieves details of a specific transaction.
* `simulate-transaction`: Simulates a transaction to check validity and expected fee.


import { ProviderRequest } from "@/components/Rapidfire/ProviderRequest.tsx";

## eth\_accounts

### Request

```ts
type Request = {
  method: "eth_accounts";
};
```

### Response

Array of connected Account addresses.

```ts
type Response = `0x${string}`[];
```

### Example

<ProviderRequest
  request={{
  method: "eth_accounts",
}}
  transformResultCode={(x) => `const accounts = ${x};`}
/>

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

```ts
import RapidfireID from "@rapidfire/id";

const rapidfire = new RapidfireID();
const provider = rapidfire.getEthereumProvider();
const accounts = await provider.request({ method: "eth_accounts" }); // [!code focus]
```


import { ProviderRequest } from "@/components/Rapidfire/ProviderRequest.tsx";

## eth\_requestAccounts

Requests access to Account addresses.

:::info
The `eth_requestAccounts` methods effectively "connects" an Application to a Wallet.
:::

### Request

```ts
type Request = {
  method: "eth_requestAccounts";
};
```

### Response

Array of connected Account addresses.

```ts
type Response = `0x${string}`[];
```

### Example

<ProviderRequest
  request={{
  method: "eth_requestAccounts",
}}
  transformResultCode={(x) => `const accounts = ${x};`}
/>

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

```ts
import RapidfireID from "@rapidfire/id";

const rapidfire = new RapidfireID();
const provider = rapidfire.getEthereumProvider();

const accounts = await provider.request({ method: "eth_requestAccounts" });// [!code focus]
```


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest'
import { encodeFunctionData, parseAbi, parseEther } from 'viem'

## eth\_sendTransaction

Instructs the Wallet to broadcast a transaction to the network.

:::warning
This method is deprecated and exists for compatibility. Please [use `wallet_sendCalls` instead](/docs/products/cross-app-wallet/rpc/wallet_sendCalls).
:::

### Request

```ts
type Request = {
  method: 'eth_sendTransaction',
  params: [{
    /** Target chain ID. Defaults to the connected chain. */
    chainId?: `0x${string}`,
    /** Calldata to send with the transaction. */
    data?: `0x${string}`,
    /** Address of the sender. */
    from: `0x${string}`,
    /** Address of the recipient. */
    to: `0x${string}`,
    /** Value to transfer. Defaults to 0. */
    value?: `0x${string}`,
  }]
}
```

### Response

Transaction hash.

```ts
type Response = `0x${string}`
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

#### Mint ERC20 Tokens

The example below demonstrates minting 100 EXP.

<ProviderRequest
  fn={async ({ provider }) => {
  const exp = {
    address: '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c',
    abi: parseAbi([
      'function mint(address, uint256)',
    ]),
  }

  const [account] = await provider.request({
    method: 'eth_accounts',
  })

  const hash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      from: account,
      // @ts-expect-error
      to: exp.address,
      data: encodeFunctionData({
        abi: exp.abi,
        functionName: 'mint',
        args: [account, parseEther('100')],
      }),
    }],
  })
  
  return hash
}}
  transformResultCode={(x) => `const txHash = \n  ${x};`}
/>

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()
import { encodeFunctionData, parseAbi, parseEther } from 'viem'

const [account] = await provider.request({
  method: 'eth_accounts',
})

const hash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c',
    data: encodeFunctionData({
      abi: parseAbi([
        'function mint(address, uint256)',
      ]),
      functionName: 'mint',
      args: [account, parseEther('100')],
    }),
  }],
})
```

#### Send ETH

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

const hash = await provider.request({// [!code focus]
  method: 'eth_sendTransaction',// [!code focus]
  params: [{// [!code focus]
    from: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',// [!code focus]
    to: '0xcafebabecafebabecafebabecafebabecafebabe',// [!code focus]
    value: '0x1',// [!code focus]
  }],// [!code focus]
})// [!code focus]
```


import { ProviderRequest } from "@/components/Rapidfire/ProviderRequest";

## eth\_signTypedData\_v4

Signs [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data.

### Request

```ts
type Request = {
  method: "eth_signTypedData_v4";
  params: [
    /** Address of the signer. */
    address: `0x${string}`,
    /** Serialized typed data to sign. */
    data: string
  ];
};
```

### Response

Signature.

```ts
type Response = `0x${string}`;
```

### Example

{/* <ProviderRequest
  fn={async ({ provider }) => {
    const hash = await provider.request({
      method: 'eth_signTypedData_v4',
      params: [
        "0x3b7252d007059ffc82d16d022da3cbf9992d2f70",
        {
          "types": {
            "EIP712Domain": [
              { "name": "name", "type": "string" },
              { "name": "version", "type": "string" },
              { "name": "chainId", "type": "uint256" },
              { "name": "verifyingContract", "type": "address" }
            ],
            "Person": [
              { "name": "name", "type": "string" },
              { "name": "wallet", "type": "address" }
            ]
          },
          "primaryType": "Person",
          "domain": {
            "name": "Example App",
            "version": "1",
            "chainId": 1,
            "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
          },
          "message": {
            "name": "Alice",
            "wallet": "0x3b7252d007059ffc82d16d022da3cbf9992d2f70"
          }
        }
      ],
    })

    return hash
  }}
  transformResultCode={(x) => `const txHash = ${x};`}
  /> */}

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

```ts
import RapidfireID from "@rapidfire/id";

const rapidfire = new RapidfireID();
const provider = rapidfire.getEthereumProvider();

const signature = await provider.request({// [!code focus]
  method: "eth_signTypedData_v4",// [!code focus]
  params: ["0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", "..."],// [!code focus]
});// [!code focus]
```


## RPC Methods Overview

### Methods

| Method                                                                                     | Description                                                                        | Standard                                                                                                    |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`eth_accounts`](/docs/products/cross-app-wallet/rpc/eth_accounts)                         | Returns an array of all **connected** Account addresses.                           | [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474)                                                         |
| [`eth_requestAccounts`](/docs/products/cross-app-wallet/rpc/eth_requestAccounts)           | Requests access to Account addresses.                                              |                                                                                                             |
| [`eth_sendTransaction`](/docs/products/cross-app-wallet/rpc/eth_sendTransaction)           | Broadcasts a transaction to the network.                                           | [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474)                                                         |
| [`eth_signTypedData_v4`](/docs/products/cross-app-wallet/rpc/eth_signTypedData_v4)         | Signs [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data.                | [EIP-712](https://eips.ethereum.org/EIPS/eip-712)                                                           |
| [`personal_sign`](/docs/products/cross-app-wallet/rpc/personal_sign)                       | Signs an [EIP-191](https://eips.ethereum.org/EIPS/eip-191) personal message.       | [EIP-191](https://eips.ethereum.org/EIPS/eip-191)                                                           |
| [`wallet_getCapabilities`](/docs/products/cross-app-wallet/rpc/wallet_getCapabilities)     | Gets supported capabilities of global wallet.                                      | [ERC-5792](https://eips.ethereum.org/EIPS/eip-5792)                                                         |
| [`wallet_getCallsStatus`](/docs/products/cross-app-wallet/rpc/wallet_getCallsStatus)       | Gets the status of a call bundle.                                                  | [ERC-5792](https://eips.ethereum.org/EIPS/eip-5792)                                                         |
| [`wallet_sendCalls`](/docs/products/cross-app-wallet/rpc/wallet_sendCalls)                 | Broadcast a bundle of calls to the network.                                        | [ERC-5792](https://eips.ethereum.org/EIPS/eip-5792)                                                         |
| [`wallet_grantPermissions`](/docs/products/cross-app-wallet/rpc/wallet_grantPermissions)   | Grants permissions for an Application to perform actions on behalf of the account. | [ERC-7715](https://github.com/ethereum/ERCs/blob/23fa3603c6181849f61d219f75e8a16d6624ac60/ERCS/erc-7715.md) |
| [`wallet_revokePermissions`](/docs/products/cross-app-wallet/rpc/wallet_revokePermissions) | Revokes a permission.                                                              | [ERC-7715](https://github.com/ethereum/ERCs/blob/23fa3603c6181849f61d219f75e8a16d6624ac60/ERCS/erc-7715.md) |


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest';

## personal\_sign

Signs an [EIP-191](https://eips.ethereum.org/EIPS/eip-191) personal message.

### Request

```ts
type Request = {
  method: 'personal_sign',
  params: [
    /** Message to sign. */
    message: string,
    /** Address of the signer. */
    address: `0x${string}`,
  ],
}
```

### Response

Signature.

```ts
type Response = `0x${string}`
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

<ProviderRequest
  fn={async ({ provider }) => {
  const [account] = await provider.request({
    method: 'eth_accounts',
  })

  const hash = await provider.request({
    method: 'personal_sign', 
    params: [ 
      '0x68656c6c6f20776f726c64', // "hello world" in hex
      account, 
    ], 
  })
  
  return hash
}}
/>

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

const [account] = await provider.request({
  method: 'eth_accounts',
})

const hash = await provider.request({ // [!code focus]
  method: 'personal_sign', // [!code focus]
  params: [ // [!code focus]
    '0x68656c6c6f20776f726c64', // "hello world" in hex [!code focus]
    account, // [!code focus]
  ], // [!code focus]
})// [!code focus]
```


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest.tsx';
import { encodeFunctionData, parseAbi, parseEther } from 'viem';

## wallet\_getCallsStatus

Gets the status of a call bundle sent via [`wallet_sendCalls`](/docs/products/cross-app-wallet/rpc/wallet_sendCalls).

### Request

```ts
type Request = {
  method: 'wallet_getCallsStatus',
  params: [
    /** ID of the call bundle. */
    id: `0x${string}`
  ]
}
```

### Response

```ts
type Response = {
  /** Chain ID the calls were submitted to. */
  chainId: `0x${string}`,
  /** ID of the call bundle. */
  id: `0x${string}`,
  /** Transaction receipts of the calls. */
  receipts: {
    /** Block hash. */
    blockHash: `0x${string}`,
    /** Block number. */
    blockNumber: `0x${string}`,
    /** Gas used by the transaction. */
    gasUsed: `0x${string}`,
    /** Logs of the call. */
    logs: {
      /** Address of the contract that emitted the log. */
      address: `0x${string}`,
      /** Data of the log. */
      data: `0x${string}`,
      /** Topics of the log. */
      topics: `0x${string}`[],
    }[],
    /** Status. */
    status: `0x${string}`,
    /** Transaction hash. */
    transactionHash: `0x${string}`,
  }[],
  /** Status code. See "Status Codes" below. */
  status: number
}
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

<ProviderRequest
  fn={async ({ provider }) => {
  const exp = {
    address: '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c',
    abi: parseAbi([
      'function mint(address, uint256)',
    ]),
  }

  const [account] = await provider.request({
    method: 'eth_accounts',
  })

  const mintCall = {
    from: account,
    // @ts-expect-error
    to: exp.address,
    data: encodeFunctionData({
      abi: exp.abi,
      functionName: 'mint',
      args: [account, parseEther('100')],
    }),
  }

  const hash = await provider.request({
    method: 'wallet_sendCalls',
    params: [{
      calls: [mintCall,mintCall]
    }],
  })
  
  const status = await provider.request({
    method: 'wallet_getCallsStatus',
    params: [hash],
  })

  return status
}}
  transformResultCode={(x) => `const status = ${x};`}
/>

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

const status = await provider.request({ 
  method: 'wallet_getCallsStatus', 
  params: ['0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef'], 
}) 
```


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest.tsx';

## wallet\_getCapabilities

Gets supported capabilities of the global wallet.

### Request

```ts
type Request = {
  method: 'wallet_getCapabilities',
}
```

### Response

```ts
type Response = {
  capabilities: {
    atomicBatch: {
      supported: true
    }
    createAccount: {
      supported: true
    },
    permissions: {
      supported: true
    }
  }
}
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

<ProviderRequest
  request={{
  method: "wallet_getCapabilities",
}}
  transformResultCode={(x) => `const capabilities = ${x};`}
/>

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

const capabilities = await provider.request({ 
  method: 'wallet_getCapabilities', 
}) 
```


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest.tsx';

## wallet\_grantPermissions

Grants permissions for an Application to perform actions on behalf of the account. Based on [ERC-7715](https://github.com/ethereum/ERCs/blob/23fa3603c6181849f61d219f75e8a16d6624ac60/ERCS/erc-7715.md).

### Request

```ts
type Request = {
  method: 'wallet_grantPermissions',
  params: [{
    /** 
     * Address of the account to grant permissions on. 
     * Defaults to the current account. 
     */
    address?: `0x${string}`

    /** Chain ID to grant permissions on. */
    chainId?: `0x${string}`

    /** Expiry of the permissions. */
    expiry: number

    /** Key to grant permissions to. Defaults to a wallet-managed key. */
    key?: {
      /** 
       * Public key. 
       * Accepts an address for `address` & `secp256k1` types. 
       */
      publicKey?: `0x${string}`,
      /** Key type. */
      type?: 'address' | 'p256' | 'secp256k1' | 'webauthn-p256', 
    }
    
    /** Permissions to grant. */
    permissions: {
      /** Call permissions. */
      calls: {
        /** Function signature or 4-byte signature. */
        signature?: string
        /** Authorized target address. */
        to?: `0x${string}`
      }[],
    },
  }]
}
```

### Response

```ts
type Response = {
  address: `0x${string}`,
  chainId: `0x${string}`,
  expiry: number,
  id: `0x${string}`,
  key: {
    publicKey: `0x${string}`,
    type: 'address' | 'p256' | 'secp256k1' | 'webauthn-p256',
  },
  permissions: {
    calls: {
      signature?: string,
      to?: `0x${string}`,
    }[],
  },
}
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

The example below demonstrates granting permissions for an Application to perform `transfer` calls on the EXP ERC20 contract,
with a spending limit of up to `50 EXP` per day.

:::info
Once permissions have been granted, they will be automatically applied to any calls made by the Application
via [`wallet_sendCalls`](/docs/products/cross-app-wallet/rpc/wallet_sendCalls) or [`eth_sendTransaction`](/docs/products/cross-app-wallet/rpc/eth_sendTransaction).
:::

{/* <ProviderRequest
  fn={async ({ provider }) => {

    const token = '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c'

    const permissions = await provider.request({
      method: 'wallet_grantPermissions',
      params: [{
        expiry: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60, // 1 week
        permissions: [{
          calls: [{ 
            signature: 'transfer(address,uint256)',
            to: token
          }],
        }],
      }],
    })

    return permissions
  }}
  transformResultCode={(x) => `const status = ${x};`}
  /> */}

```ts
import RapidfireID from '@rapidfire/id'
import { parseEther, toHex } from 'viem'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

const token = '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c'

const permissions = await provider.request({
  method: 'wallet_grantPermissions',
  params: [{
    expiry: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60, // 1 week
    permissions: {
      calls: [{ 
        signature: 'transfer(address,uint256)',
        to: token
      }],
    },
  }],
})
```


## wallet\_revokePermissions

Revokes a permission.

### Request

```ts
type Request = {
  method: 'wallet_revokePermissions',
  params: [{
    /** Address of the account to revoke a permission on. */
    address?: `0x${string}`
    /** ID of the permission to revoke. */
    id: `0x${string}`
  }]
}
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()

await provider.request({
  method: 'experimental_revokePermissions',
  params: [{ id: '0x...' }],
})
```


import { ProviderRequest } from '@/components/Rapidfire/ProviderRequest.tsx';
import { encodeFunctionData, parseAbi, parseEther } from 'viem';

## wallet\_sendCalls

Requests for the Wallet to broadcast a bundle of calls to the network.

### Request

```ts
type Request = {
  method: 'wallet_sendCalls',
  params: [{
    /** Calls to prepare. */
    calls: {
      /** Recipient. */
      to: `0x${string}`;
      /** Calldata. */
      data?: `0x${string}`;
      /** Value to transfer. */
      value?: `0x${string}`;
    }[];
    /** 
     * Chain ID to send the calls to.
     * If not provided, the current chain will be used.
     */
    chainId?: `0x${string}`;
    /** 
     * Address of the account to send the calls from.
     * If not provided, the Account will be filled by the Wallet.
     */
    from?: `0x${string}`;
    /** Capabilities. */
    capabilities?: {
      permissions?: {
        /** ID of the permission to use. */
        id: `0x${string}`;
      };
    };
  }]
}
```

### Response

```ts
type Response = {
  /** ID of the bundle. */
  id: string;
}
```

### Example

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

#### Mint ERC20 Tokens

The example below demonstrates minting 100 EXP twice.

<ProviderRequest
  fn={async ({ provider }) => {
  const exp = {
    address: '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c',
    abi: parseAbi([
      'function mint(address, uint256)',
    ]),
  }

  const [account] = await provider.request({
    method: 'eth_accounts',
  })

  const mintCall = {
    from: account,
    // @ts-expect-error
    to: exp.address,
    data: encodeFunctionData({
      abi: exp.abi,
      functionName: 'mint',
      args: [account, parseEther('100')],
    }),
  }

  const hash = await provider.request({
    method: 'wallet_sendCalls',
    params: [{
      calls: [mintCall,mintCall]
    }],
  })
  
  return hash
}}
  transformResultCode={(x) => `const id = ${x};`}
/>

```ts
import RapidfireID from '@rapidfire/id'
import { encodeFunctionData, parseAbi, parseEther } from 'viem'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()


const [account] = await provider.request({
  method: 'eth_accounts',
})

const hash = await provider.request({ 
  method: 'wallet_sendCalls', 
  params: [{ 
    calls: [{ 
      to: '0x706aa5c8e5cc2c67da21ee220718f6f6b154e75c', 
      data: encodeFunctionData({ 
        abi: parseAbi([ 
          'function mint(address, uint256)', 
        ]), 
        functionName: 'mint', 
        args: [account, parseEther('100')], 
      }), 
    }], 
  }], 
}) 
```

#### Send a Transaction

```ts
import RapidfireID from '@rapidfire/id'

const rapidfire = new RapidfireID()
const provider = rapidfire.getEthereumProvider()


const response = await provider.request({ 
  method: 'wallet_sendCalls', 
  params: [{ 
    calls: [{ 
      to: '0xcafebabecafebabecafebabecafebabecafebabe', 
      value: '0x12345678', 
    }], 
  }] 
}) 
```


## FAQs

#### Can Openfort support my ecosystem's login system?

Yes, Openfort's architecture is built to allow thousands of new gaming ecosystems flourish. You ecosystem can be added as an OAuth provider allowing your community to be recognized.

#### What if I can't find my authentication provider in the documentation?

No problem, let us know which provider you want to use and we'll get right into it.

#### Can players use their existing wallets alongside Openfort Auth?

Users can link existing wallets to their account. This allows you to store and share these wallet addresses with games via the SDK for read-only use.

#### What level of support and Service Level Agreements (SLAs) are provided?

At Openfort, we understand the significance of maintaining a high standard of service. Our Service Level Agreements (SLAs) reflect our commitment to providing a reliable, efficient, and safe environment for your operations.

### Security and Contingency Planning

#### If Openfort were to shut down with a one-month notice, would there be scope to change the signer on the Smart Contract Wallet and use it in connection with a different provider that manages the private keys differently?

**TLDR:** With enough time, transitioning is fairly simple. You’d need to invoke the `transferOwnership` function for users to accept the new signer.

**Detailed Answer:** Yes, if Openfort shuts down with a one-month notice, it's possible to change the signer. Since Openfort wallets are non-custodial, users have control over their private keys. The key migration process would involve using the "recovery share" and "device share" from Shamir's Secret Sharing (SSS) to reconstruct the private key, allowing users to accept a new signer through the `transferOwnership` function. The new provider would need to support compatible key management systems.

#### If Openfort were shut down with zero notice, would there be any scope to do a migration? Would that rely on a self-hosted Shield for the recovery share and the device share being intact?

**TLDR:** If there is no self-hosted option, users should rely on on-chain social recovery.

**Detailed Answer:** Migration is still possible, but it depends on the self-hosted Shield for the recovery share and the availability of the device share. If a self-hosted Shield is not in place, users can utilize on-chain social recovery. As long as the device share and recovery share are intact, users can reconstruct their private key and migrate to a new provider. On-chain social recovery can also help recover the wallet if the device share is lost.

#### If Openfort's API were compromised, what is the risk there? Can that risk be mitigated? What’s the risk of the auth share on the private key being exposed?

**TLDR:** Both Openfort's server and Shield are encrypted. Even if an attacker obtains the auth share, they would need a secret to decrypt it.

**Detailed Answer:** If Openfort's API were compromised, the risk is limited because both the auth share and Shield service are encrypted. Even if an attacker gains access to the auth share, they would still need to decrypt it using a secret. Furthermore, since the private key is split using Shamir's Secret Sharing, the auth share alone is insufficient to reconstruct the full key without the device or recovery share.


## Why create a Global Wallet?

Embedded wallets typically require each application to manage its own wallet setup.

<div align="center">
  <img alt="Diagram showing separate embedded wallets within isolated apps" src="https://blog-cms.openfort.io/uploads/embedded_wallet_architecture_1629fefe7b.jpg" width="80%" height="80%" />
</div>

This can lead to several challenges:

* **Fragmented authentication across apps**
  When each app manages its own authentication, you end up with duplicated logic, inconsistent session handling, and a messy user experience. OAuth2 providers struggle to maintain continuity across domains, making it difficult to track a user's identity and wallet access holistically.

* **Liquidity fragmentation kills network effects**
  If every app generates and manages its own wallets, user assets are scattered across isolated accounts. This makes it harder to build shared economies, pooled inventories, or unified user profiles—preventing the kind of liquidity and composability that ecosystems need to thrive.

* **No interoperability across apps**
  Different wallet implementations across apps lead to incompatibilities in how users onboard, transact, or authorize actions. Without a shared interface or contract standard, there's no guarantee that features like cross-app identity, shared balances, or seamless UX will work consistently.

### How does Openfort Global Wallets solve this?

<div align="center">
  <img alt="Global wallet architecture that centralizes wallet management" src="https://blog-cms.openfort.io/uploads/ecosystem_architecture_3b71d2591d.jpg" width="80%" height="80%" />
</div>

Switching to an ecosystem approach addresses the challenges of embedded wallets:

* **Unified authentication:** A single sign-on mechanism minimizes friction and simplifies session management across apps.
* **Monitoring and user management:** Manage all user permissions from a single dashboard. This empowers administrators to monitor activities and enforce security policies consistently.
* **Enhanced developer experience:** One integration point means your team can focus on building features rather than managing multiple wallet configurations.
* **Consistent user experience:** Provide a seamless and intuitive wallet experience regardless of which app the user interacts with.

### Ecosystem SDK: Deep Dive

The Openfort Ecosystem SDK is a modular system, with each package playing a specific role in enabling secure, global wallet experiences.

#### `@openfort/ecosystem/client`

* Announces a provider using both [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) and [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), making it compatible with popular Ethereum tooling (e.g., wagmi, viem).
* Initiates a signer (via the `SCWSigner` class), which is responsible for transaction signing and secure communication.
* All communication is based on window messaging (using `postMessage`), either between an iframe and the main page or between a popup and its parent.
* The provider's `request` method wraps JSON-RPC requests and forwards them through the communicator, which handles the secure postMessage exchange.
* The secure channel is established with the wallet UI (where the user interacts), following the [Mobile Wallet Protocol (MWP)](https://github.com/mobile-wallet-protocol).
* The `SCWKeyManager` manages the secure key exchange and communication.

#### `@openfort/ecosystem/core`

* Acts as the **bridge** between the client SDK (in the app) and the wallet UI (the user-facing component).
* Installed in the wallet UI, it handles the other end of the communication with the client SDK via MWP.
* Exposes helper functions for reading incoming requests and sending responses.
* Stores session data (key pairs for Diffie-Hellman exchange) per app, based on the origin, in local storage. This allows multiple secure channels for different apps.
* If storage is cleared, a new handshake and key exchange are required.
* Because it's MWP-compatible, you can use platform-specific libraries (e.g., Unity) for wallet UIs.

#### `@openfort/ecosystem/react`

* Provides React-specific helpers and a set of prebuilt components and a styling library (inspired by ConnectKit) to bootstrap wallet UIs quickly.
* Contains React wrappers for invoking `@openfort/core` methods.
* Used in the sample wallet UI at [id.sample.openfort.io](https://id.sample.openfort.io), which demonstrates how to build a wallet front-end using these prebuilt components.
* The sample uses the Openfort Embedded Signer for key management, but other implementations (e.g., Safe, on-chain passkey) are possible.

#### `@openfort/ecosystem-js`

* Re-exports everything from the above packages, providing a single entry point for all SDK functionality.

### Architecture

<div align="center">
  <img alt="Architectural diagram of Ecosystem SDK" src="https://blog-cms.openfort.io/uploads/fort_framework_1e74c0aee1.svg" width="70%" height="70%" />
</div>

### Core Components

* **Client SDK (`@openfort/ecosystem/client`):**\
  The "head chef" of the wallet system, handling wallet creation, UI pop-ups, and transaction management. EIP-1193 compatible.

* **Communication module (`@openfort/ecosystem/core`):**\
  The bridge between the app and the wallet UI, handling secure communication and session management via MWP.

* **Framework prefabs (`@openfort/ecosystem/react`):**\
  Prebuilt React components and styling helpers to accelerate wallet UI development.

* **Ecosystem entrypoint (`@openfort/ecosystem-js`):**\
  A unified package that re-exports all SDK modules for convenience.


## Batch transactions

Smart Wallet enables you to send multiple onchain calls in a single transaction, improving UX by reducing multi-step interactions to a single click. A common example is combining an ERC-20 `approve` with a swap operation.

You can submit batch transactions using the new `wallet_sendCalls` [RPC](https://eip5792.xyz/reference/sendCalls) method.

:::steps
#### Check wallet compatibility for atomic batching

First, verify if your app supports atomic batching (This step is crucial if your app supports multiple wallet types). Use the `useCapabilities` hook from Wagmi experimental features and implement fallback functionality for unsupported wallets.

Note: The `useWriteContracts` and `useCapabilities` hooks rely on new wallet RPC and may not be supported in all wallets.

```typescript app.tsx
import { useCapabilities } from 'wagmi/experimental'

function App() {
  const { data: capabilities } = useCapabilities() 
  // Returns capability object per chain:
  // {
  //   84532: {
  //     atomicBatch: {
  //       supported: true,
  //     },
  //   }  
  // }
  
  // Check if atomic batching is supported in the chain we want to interact with
  const isAtomicBatchSupported = capabilities?.[84532]?.atomicBatch?.supported
  
  return (
    <div>
      {isAtomicBatchSupported ? (
        <BatchTransactionComponent />
      ) : (
        <FallbackComponent />
      )}
    </div>
  )
}
```

#### Set up contract interactions

Import required hooks: `useAccount` and `useWriteContracts` from Wagmi, define your smart contract ABI, initialize the `useWriteContracts` hook for batch transactions, and create a transaction handling function that can process multiple contract calls.

Important: Make sure your contract ABIs are correctly typed for better development experience.

```typescript app.tsx
import { useAccount } from 'wagmi'
import { useWriteContracts } from 'wagmi/experimental'

// Define your contract ABI
const abi = [
  {
    stateMutability: 'nonpayable',
    type: 'function',
    inputs: [{ name: 'to', type: 'address' }],
    name: 'safeMint',
    outputs: [],
  }
] as const

function BatchTransactionComponent() {
  const account = useAccount()
  const { writeContracts } = useWriteContracts()

  const handleBatchTransaction = () => {
    writeContracts({
      contracts: [
        {
          address: "0x119Ea671030FBf79AB93b436D2E20af6ea469a19",
          abi,
          functionName: "safeMint",
          args: [account.address],
        },
        // Add more contract interactions as needed
        {
          address: "0x119Ea671030FBf79AB93b436D2E20af6ea469a19",
          abi,
          functionName: "safeMint",
          args: [account.address],
        }
      ],
    })
  }

  return (
    <button 
      onClick={handleBatchTransaction}
      className="px-4 py-2 bg-blue-600 text-white rounded"
    >
      Execute Batch Transaction
    </button>
  )
}
```

#### Implement transaction status monitoring

Add the `useCallsStatus` hook to track transaction status, configure polling interval for status updates, display transaction status to users, and handle transaction completion and errors.

Pro tip: The polling interval can be adjusted based on your needs, but 1 second is a good default.

```typescript app.tsx
import { useCallsStatus } from 'wagmi/experimental'

function BatchTransactionComponent() {
  const { data: id, writeContracts } = useWriteContracts()
  const { data: callsStatus } = useCallsStatus({
    id: id as string,
    query: {
      enabled: !!id,
      // Poll every second until confirmed
      refetchInterval: (data) =>
        data.state.data?.status === "CONFIRMED" ? false : 1000,
    },
  })

  // Example response structure:
  // {
  //   status: 'CONFIRMED',
  //   receipts: [
  //     {
  //       logs: [{
  //         address: '0x...',
  //         topics: ['0x...'],
  //         data: '0x...'
  //       }],
  //       status: 'success',
  //       blockHash: '0x...',
  //       blockNumber: 122414523n,
  //       gasUsed: 390000n,
  //       transactionHash: '0x...'
  //     }
  //   ]
  // }

  return (
    <div className="space-y-4">
      <button 
        onClick={handleBatchTransaction}
        className="px-4 py-2 bg-blue-600 text-white rounded"
      >
        Execute Batch Transaction
      </button>
      
      {callsStatus && (
        <div className="p-4 border rounded">
          <p className="font-semibold">
            Status: {callsStatus.status}
          </p>
          {callsStatus.status === 'CONFIRMED' && (
            <p className="text-green-600">
              Transaction confirmed! Hash: {callsStatus.receipts[0].transactionHash}
            </p>
          )}
        </div>
      )}
    </div>
  )
}
```
:::


## Build a "Create Wallet" button

For the best onboarding experience, we recommend adding a highly visible 'Create' or 'Create Wallet' button to your app's homepage. Adding this button streamlines the onboarding experience for new users and gets them ready to use your app in a few seconds.

Here is an example of how the button looks:

<div align="left">
  <img alt="create-wallet-button" src="https://blog-cms.openfort.io/uploads/createwallet_81b193f481.png" width="30%" height="30%" />
</div>

### Implementation with Wagmi

<div>
  To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID** using the Ecosystem SDK. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

  You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
</div>

<div>
  Using Wagmi offers a balanced approach that combines flexibility with developer convenience. By integrating the global wallet with Wagmi, you get access to a comprehensive set of React hooks that handle common wallet operations, state management, and chain interactions. This approach requires both `@rapidfire/id` and `Wagmi` dependencies, along with React Query, but provides a more structured development experience. While you'll still need to build your own UI components, Wagmi's hooks significantly reduce the complexity of handling wallet connections, transactions, and chain switching.
</div>

:::steps
#### Configure Wagmi

First, set up your Wagmi configuration with the required chain and connector settings.

```ts wagmi.ts
import { http, createConfig } from 'wagmi';
import { polygonAmoy } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [polygonAmoy],
  connectors: [
    injected(),
  ],
  transports: {
    [polygonAmoy.id]: http(),
  },
});

declare module 'wagmi' {
  interface Register {
    config: typeof config;
  }
}
```

#### Implement the Create Wallet Button (Wagmi)

Create the main button component using Wagmi's useConnect hook. This uses the WalletLogo component defined in the previous step.

```tsx [CreateWalletButton.tsx]
import React, { useCallback } from 'react';
import { useConnect } from 'wagmi';
import { WalletLogo } from './WalletLogo';

const buttonStyles = {
  background: 'linear-gradient(135deg, #2D3436 0%, #000000 100%)',
  border: '1px solid rgba(255, 255, 255, 0.1)',
  boxSizing: 'border-box' as const,
  display: 'flex',
  alignItems: 'center',
  gap: '12px',
  width: 'auto',
  minWidth: '200px',
  fontFamily: 'Inter, system-ui, sans-serif',
  fontWeight: '600',
  fontSize: '16px',
  color: '#FFFFFF',
  padding: '12px 20px',
  borderRadius: '12px',
  cursor: 'pointer',
  transition: 'all 0.2s ease-in-out',
  boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',
  ':hover': {
    transform: 'translateY(-1px)',
    boxShadow: '0 6px 8px -1px rgba(0, 0, 0, 0.1), 0 4px 6px -1px rgba(0, 0, 0, 0.06)',
  },
};

export function CreateWalletButton() {
  const { connectors, connect, data } = useConnect();

  const createWallet = useCallback(() => {
    const injectedConnector = connectors.find(
      // Here you'd write your own connector ID as per the one you configured in the wallet SDK
      (connector) => connector.id === 'com.rapidfire.id'
    );
    if (injectedConnector) {
      connect({ connector: injectedConnector });
    }
  }, [connectors, connect]);

  return (
    <button style={buttonStyles} onClick={createWallet}>
      <WalletLogo />
      Create Wallet
    </button>
  );
}
```
:::

<div>
  **Notes:** For more detail, view the [`useConnect` documentation](https://wagmi.sh/react/api/hooks/useConnect).
  Upon successful connection, account information can be accessed via [data](https://wagmi.sh/react/api/hooks/useConnect#data) returned from `useConnect`, or via [`useAccount`](https://wagmi.sh/react/api/hooks/useAccount).
</div>

### Implementation with EIP-1193 Provider

<div>
  The EIP-1193 Provider approach gives you the most granular control over your global wallet integration by directly using the SDK's Ethereum provider. This method requires only the `@rapidfire/id` package and allows you to build everything from scratch. You'll handle all wallet interactions through the standard `EIP-1193` provider interface, giving you complete flexibility in implementing wallet creation, connection flows, and transaction handling. While this approach requires more custom development work, it's ideal for applications that need specialized wallet interactions or want to minimize dependencies.
</div>

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

::::steps
#### Initialize the SDK, Provider, and Components

Create a new SDK instance with your application configuration, set up the Ethereum provider, and define reusable components.

:::tip
Make sure to set up your `NEXT_PUBLIC_POLICY_ID` in your environment variables.
:::

:::code-group
```ts [sdk.ts]
import EcosystemWallet from '@rapidfire/id';

// Initialize the SDK with required parameters
export const sdk = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```

```ts [provider.ts]
import { sdk } from './sdk';

// Configure the provider with chain and policy
export const provider = sdk.getEthereumProvider({
  policy: process.env.NEXT_PUBLIC_POLICY_ID
});
```

```tsx [WalletLogo.tsx]
import React from 'react';

const defaultContainerStyles = {
  paddingTop: 2,
  display: 'flex',
  alignItems: 'center',
};

export function WalletLogo({
  size = 24,
  containerStyles = defaultContainerStyles,
}) {
  return (
    <div style={containerStyles}>
      <svg
        width={size}
        height={size}
        viewBox="0 0 24 24"
        fill="none"
        xmlns="http://www.w3.org/2000/svg"
      >
        <rect
          x="2"
          y="4"
          width="20"
          height="16"
          rx="3"
          stroke="currentColor"
          strokeWidth="2"
        />
        <path
          d="M16 12C16 10.8954 16.8954 10 18 10H22V14H18C16.8954 14 16 13.1046 16 12Z"
          fill="currentColor"
        />
        <circle cx="12" cy="12" r="2" fill="currentColor" />
      </svg>
    </div>
  );
}
```
:::

#### Implement the Create Wallet Button

Create the button component that uses the configured provider.

```tsx [CreateWalletButton.tsx]
import React, { useCallback } from 'react';
import { WalletLogo } from './WalletLogo';
import { provider } from './provider';

const buttonStyles = {
  background: 'linear-gradient(135deg, #2D3436 0%, #000000 100%)',
  border: '1px solid rgba(255, 255, 255, 0.1)',
  boxSizing: 'border-box' as const,
  display: 'flex',
  alignItems: 'center',
  gap: '12px',
  width: 'auto',
  minWidth: '200px',
  fontFamily: 'Inter, system-ui, sans-serif',
  fontWeight: '600',
  fontSize: '16px',
  color: '#FFFFFF',
  padding: '12px 20px',
  borderRadius: '12px',
  cursor: 'pointer',
  transition: 'all 0.2s ease-in-out',
  boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',
  ':hover': {
    transform: 'translateY(-1px)',
    boxShadow: '0 6px 8px -1px rgba(0, 0, 0, 0.1), 0 4px 6px -1px rgba(0, 0, 0, 0.06)',
  },
};

export function CreateWalletButton({ handleSuccess, handleError }) {
  const createWallet = useCallback(async () => {
    try {
      const [address] = await provider.request({
        method: 'eth_requestAccounts',
      });
      handleSuccess(address);
    } catch (error) {
      handleError(error);
    }
  }, [handleSuccess, handleError]);

  return (
    <button style={buttonStyles} onClick={createWallet}>
      <WalletLogo />
      Create Wallet
    </button>
  );
}
```
::::


## Sponsor transactions

One of the biggest UX enhancements unlocked by smart accounts is the ability for app developers to sponsor their users' transactions. If your ecosystem has a gas policy enabled, you can start sponsorship your user's transactions by using the `policy` in your [dashboard](https://dashboard.openfort.io/policies).

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

### Use a policy when injecting your provider

Sponsor all transactions that will be made with the injected provider.

:::code-group
```tsx [app.tsx]
import { sdk } from './sdk'

function App() {
  useEffect(() => {
    sdk.getEthereumProvider({policy: 'pol_...'});
  }, []);
  return (
    <div/>
  )
}
```

```ts [sdk.ts]
import EcosystemWallet from '@rapidfire/id'

// Initialize the SDK with required parameters
export const sdk = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```
:::

### Updating the policy

Updating your policy is useful if you change chain and need to specify a different policy ID.

:::code-group
```tsx [app.tsx]
import { sdk } from './sdk'

function App() {
  useEffect(() => {
    sdk.setPolicy({policy: 'pol_...'});
  }, []);
  return (
    <div/>
  )
}
```

```ts [sdk.ts]
import EcosystemWallet from '@rapidfire/id'

// Initialize the SDK with required parameters
export const sdk = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```
:::

***

You can also configure your own app level policy. Check the details in the [dashboard section](/docs/configuration/gas-sponsorship).

* Using an [**external paymaster** setup.](/docs/configuration/gas-sponsorship#optional-using-external-paymasters)

* Learn how to [use **erc20 tokens**](/docs/configuration/gas-erc20) to pay for gas fees.


## Integrating with wallet connectors

Using a **wallet library** provides the most streamlined path to implementing a wallet UI, offering a complete solution with pre-built UI components and a polished user experience out of the box. This approach builds on top of Wagmi and includes additional UI components like the `ConnectButton`, ready-to-use themes, and built-in transaction interfaces. While it requires the most dependencies (`@rapidfire/id`, `Wagmi`, `React Query`, and `RainbowKit` -for example), it significantly reduces development time by providing a complete wallet interface solution.

<div>
  To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

  You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
</div>

### Getting an EIP-1193 provider

All of Ecosystem SDK wallets can export a standard [EIP-1193 provider](https://eips.ethereum.org/EIPS/eip-1193) object. This allows your app to request signatures and transactions from the wallet, using familiar JSON-RPC requests like `personal_sign` or `eth_sendTransaction`.

<div>
  [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), also known as the Ethereum JavaScript API, is a standardized interface for how applications can request information, signatures, and transactions from a connected wallet.
</div>

To get a wallet's EIP-1193 provider, use the `getEthereumProvider` method:

```tsx main.tsx
import { ecosystemWalletInstance } from "./rapidfireConfig"

// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = await ecosystemWalletInstance.getEthereumProvider();
```

```ts rapidfireConfig.ts
import EcosystemWallet from '@rapidfire/id';

export const ecosystemWalletInstance = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});

```

When requesting signatures and transactions from the wallet, you can either choose to interface with the **EIP-1193** provider directly, or to pass it to a library like `wagmi` or `viem`.

<div>
  If you want to check out the sample using the `@rapidfire/id` directly, you can find it in the [Rapidfire SDK repository](https://github.com/openfort-xyz/ecosystem-sample/tree/main/usage-examples/wagmi-nextjs). You will see it includes examples using [ethers](https://docs.ethers.org/v5/), [connectKit](https://docs.family.co/connectkit), [rainbowKit](https://www.rainbowkit.com/) and [wagmi](https://wagmi.sh/).
</div>

### Implementation with RainbowKit

<div align="center">
  <img alt="ecosystem-rainbow-kit" src="https://blog-cms.openfort.io/uploads/rainbow_kit_ecosystem_cf5574e8a2.png" width="80%" height="80%" />
</div>

#### 1. Install dependencies

Install the `@rapidfire/id` SDK and its peer dependencies:

```bash
npm i @rapidfire/id @rainbow-me/rainbowkit @tanstack/react-query
```

#### 2. Create the connector

```ts config.ts
import EcosystemWallet from '@rapidfire/id';

export const identityInstance = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```

#### 3. Wrap app with providers

At the highest level of your applications, wrap the component with the wagmi, QueryClient, and RainbowKit providers. Pass the configuration you created in step 2 to the wagmi provider.

All of **global wallets** can export a standard [EIP-1193 provider](https://eips.ethereum.org/EIPS/eip-1193) object. This allows your app to request signatures and transactions from the wallet, using familiar JSON-RPC requests like `personal_sign` or `eth_sendTransaction`.

<div>
  [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), also known as the Ethereum JavaScript API, is a standardized interface for how applications can request information, signatures, and transactions from a connected wallet.
</div>

To get a wallet's EIP-1193 provider, use the `getEthereumProvider` method:

```tsx _app.tsx
import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
import {WagmiProvider} from 'wagmi';
import {polygonAmoy} from 'wagmi/chains';
import {useEffect} from 'react';
import {config} from './wagmiConfig';
import {identityInstance} from './config';

const queryClient = new QueryClient();

export default function App() {
  useEffect(() => {
    if (!identityInstance) return;
    identityInstance.getEthereumProvider();
  }, []);

  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Component {...pageProps} />
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

```ts wagmiConfig.ts
import {http, createConfig} from 'wagmi';
import {polygonAmoy} from 'wagmi/chains';
import {injected} from 'wagmi/connectors';

export const config = createConfig({
  chains: [polygonAmoy],
  connectors: [injected()],
  ssr: true,
  transports: {
    [polygonAmoy.id]: http(),
  },
});
```

```ts config.ts
import EcosystemWallet from '@rapidfire/id';

export const identityInstance = new EcosystemWallet({
  appChainIds: [80002],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```

#### 4. Use the `ConnectButton`

Import the `ConnectButton` and use to prompt users to connect to their provider **global wallet**.

```tsx
import {ConnectButton} from '@rainbow-me/rainbowkit';

function Page() {
  return (
    <div>
      <h1> My app </h1>
      ...
      <ConnectButton />
    </div>
  );
}
```

Thats it! You can now use any wagmi hook in your application to interact with the connected wallet. When users connect and transact with their wallet, Openfort will open a pop-up for users to authorize any actions.


## Create a React Native App

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

This guide will walk you through adding support for any **global wallet** into a React Native app by integrating the [Mobile Wallet Protocol Client](https://www.npmjs.com/package/@mobile-wallet-protocol/client).

<div className="admonition tip">
  If you need a template or scaffold to start with, you can check out the [Global Wallet Expo Example](https://github.com/openfort-xyz/ecosystem-wallet-expo-example).
</div>

### Prerequisites

#### Install peer dependencies

The Mobile Wallet Protocol Client library requires the [Expo WebBrowser](https://docs.expo.dev/versions/latest/sdk/webbrowser/) and [Async Storage](https://react-native-async-storage.github.io/async-storage/docs/install) packages to be installed.
Follow the instructions on the respective pages for any additional setup.

```zsh [npm]
npm i expo expo-web-browser @react-native-async-storage/async-storage
```

```zsh [yarn]
yarn add expo expo-web-browser @react-native-async-storage/async-storage
```

#### Polyfills

Mobile Wallet Protocol Client requires `crypto.randomUUID`, `crypto.getRandomValues`, and `URL` to be polyfilled globally since they are not available in the React Native environment.

Below is an example of how to polyfill these functions in your app using the [expo-crypto](https://docs.expo.dev/versions/latest/sdk/crypto/) and [expo-standard-web-crypto](https://github.com/expo/expo/tree/master/packages/expo-standard-web-crypto/) packages.

```zsh [npm]
npm i expo-crypto expo-standard-web-crypto react-native-url-polyfill
```

```zsh [yarn]
yarn add expo-crypto expo-standard-web-crypto react-native-url-polyfill
```

```js [polyfills.js]
import "react-native-url-polyfill/auto";
import { polyfillWebCrypto } from "expo-standard-web-crypto";
import { randomUUID } from "expo-crypto";

polyfillWebCrypto();
crypto.randomUUID = randomUUID;
```

```tsx [App.tsx]
import "./polyfills"; // import before @mobile-wallet-protocol/client

/// ...
```

### Setup

:::steps
#### Install Mobile Wallet Protocol Client

Add the latest version of Mobile Wallet Protocol Client to your project.

```zsh [npm]
npm i @mobile-wallet-protocol/client@latest
```

```zsh [yarn]
yarn add @mobile-wallet-protocol/client@latest
```

### Usage

Mobile Wallet Protocol Client provides 2 interfaces for mobile app to interact with the Global Wallet, an EIP-1193 compliant provider interface and a wagmi connector.

<div className="admonition tip">
  If your app is using wallet aggregator, go straight to **Option 2: Wagmi Connector** for 1-line integration. :)
</div>

#### Option 1: EIP-1193 Provider

Create a new `EIP1193Provider` instance, which is EIP-1193 compliant.

```tsx [App.tsx]
import { EIP1193Provider } from "@mobile-wallet-protocol/client";

// Step 1. Initialize provider with your dapp's metadata and target wallet
const metadata = {
  name: "My App Name",
  customScheme: "myapp://", // only custom scheme (e.g. `myapp://`) is supported in v1.0.0
  chainIds: [8453],
  logoUrl: "https://example.com/logo.png",
};
const provider = new EIP1193Provider({
    metadata,
    wallet: {
        type: 'web',
        name: "Rapid fire wallet",
        // The scheme should be the target wallet's URL
        scheme: 'https://id.sample.openfort.io',
        iconUrl: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV',
    },
});

// ...

// 2. Use the provider
const addresses = await provider.request({ method: "eth_requestAccounts" });
const signedData = await provider.request({
  method: "personal_sign",
  params: ["0x48656c6c6f20776f726c6421", addresses[0]],
});
```

#### Option 2: Wagmi Connector

Add the latest verion of Mobile Wallet Protocol wagmi-connectors to your project.

```zsh [npm]
npm i @mobile-wallet-protocol/wagmi-connectors@latest
```

```zsh [yarn]
yarn add @mobile-wallet-protocol/wagmi-connectors@latest
```

Simply import the `createConnectorFromWallet` function and pass in the wallet you want to use to wagmi config.

```ts [config.ts]
import {
  createConnectorFromWallet,
  Wallets,
} from "@mobile-wallet-protocol/wagmi-connectors";

const metadata = {
  name: "My App Name",
  customScheme: "myapp://", // only custom scheme (e.g. `myapp://`) is supported in v1.0.0
  chainIds: [8453],
  logoUrl: "https://example.com/logo.png",
};

export const config = createConfig({
  chains: [base],
  connectors: [
    createConnectorFromWallet({
      metadata,
      wallet: {
        type: 'web',
        name: "Rapid fire wallet",
        scheme: 'https://id.sample.openfort.io',
        iconUrl: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV',
      },
    }),
  ],
  transports: {
    [base.id]: http(),
  },
});
```

Then you can use wagmi's react interface to interact with the Smart Wallet.

```tsx [App.tsx]
import { useConnect } from "wagmi";

// ...

const { connect, connectors } = useConnect();

return (
  <Button
    title={"Connect"}
    onPress={() => {
      connect({ connector: connectors[0] });
    }}
  />
);
```

### Gas Sponsorship

If you want to sponsor transactions, you need to add `#policy=POLICY_ID` to the wallet scheme.

```
#policy=POLICY_ID
```

For example:

```ts [config.ts]
import {
  createConnectorFromWallet,
  Wallets,
} from "@mobile-wallet-protocol/wagmi-connectors";

const metadata = {
  name: "My App Name",
  customScheme: "myapp://", // only custom scheme (e.g. `myapp://`) is supported in v1.0.0
  chainIds: [8453],
  logoUrl: "https://example.com/logo.png",
};

export const config = createConfig({
  chains: [base],
  connectors: [
    createConnectorFromWallet({
      metadata,
      wallet: {
        type: 'web',
        name: "Rapid fire wallet",
        scheme: 'https://id.sample.openfort.io#policy=pol_a909d815-9b6c-40b2-9f6c-e93505281137',
        iconUrl: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV',
      },
    }),
  ],
  transports: {
    [base.id]: http(),
  },
});
```
:::


## Signature Verification

Verifying signatures for smart contract wallets involves specific considerations since the smart contract itself cannot produce a signature. Instead, it provides a function:

```solidity
function isValidSignature(bytes32 _hash, bytes memory _signature) returns (bytes4 magicValue);
```

This function, defined in [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271), is called to verify if a given signature is valid.

For a Smart Wallet, a signature is valid if it is signed by a current signer (or "owner") of the wallet. For instance, a user might sign a message using their passkey. When the `isValidSignature` function is called on their Smart Wallet, it validates the signature because the user's passkey is authorized as an owner.

The following section outlines how to implement both personal message signing and typed data signing using wagmi.

### Message Signing

For basic message signing (personal\_sign), you can use wagmi's `useSignMessage` hook. Here's an example implementation:

```tsx
import { useSignMessage } from 'wagmi'

function SignMessage() {
  const { signMessage, data: signature, isPending, error } = useSignMessage()

  const handlePersonalSign = () => {
    signMessage({ message: 'Hello World' })
  }

  return (
    <div>
      <button 
        onClick={handlePersonalSign}
        disabled={isPending}
      >
        {isPending ? 'Signing...' : 'Sign Message'}
      </button>
      
      {signature && (
        <div>
          <p>Signature: {signature}</p>
        </div>
      )}
      
      {error && <div>Error: {error.message}</div>}
    </div>
  )
}
```

### Typed Data Signing

For more complex signatures, you can use typed data signing (EIP-712) with wagmi's `useSignTypedData` hook:

```tsx
import { useSignTypedData } from 'wagmi'

function SignTypedData() {
  const { signTypedData, data: signature, isPending, error } = useSignTypedData()

  const types = {
    Mail: [
      {name: 'from', type: 'Person'},
      {name: 'to', type: 'Person'},
      {name: 'content', type: 'string'},
    ],
    Person: [
      {name: 'name', type: 'string'},
      {name: 'wallet', type: 'address'},
    ],
  }

  const handleTypedMessage = () => {
    signTypedData({
      domain: {
        chainId: 1, // Replace with your chain ID
        name: 'Example DApp',
        verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
        version: '1',
      },
      types,
      message: {
        from: { name: 'Alice', wallet: '0x2111111111111111111111111111111111111111' },
        to: { name: 'Bob', wallet: '0x3111111111111111111111111111111111111111' },
        content: 'Hello!',
      },
      primaryType: 'Mail',
    })
  }

  return (
    <div>
      <button 
        onClick={handleTypedMessage}
        disabled={isPending}
      >
        {isPending ? 'Signing...' : 'Sign Typed Data'}
      </button>
      
      {signature && (
        <div>
          <p>Signature: {signature}</p>
        </div>
      )}
      
      {error && <div>Error: {error.message}</div>}
    </div>
  )
}
```

Both signing methods work seamlessly with Smart Contract Wallets that implement EIP-1271, allowing for a consistent signing experience across EOA and Smart Contract Wallets.


## Unity Android

:::note
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

This guide will walk you through adding support for any **global wallet** into a Unity app by integrating the [Mobile Wallet Protocol](https://mobilewalletprotocol.github.io/wallet-mobile-sdk/).

On Android, we use [Chrome Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs/) (if available) to seamlessly connect gamers to your Openfort wallet from within the game.

### Requirements

:::info
**UNITY VERSIONS BELOW 2021.3**

To check if Chrome Custom Tabs are available, older Unity versions may require a specific Gradle plugin version.
For example, on Unity 2019.4, you must upgrade from 3.4.\* to 3.4.3 (see Android's blog post):

1. In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Base Gradle Template under the Build section
2. Open the newly generated Assets/Plugins/Android/baseProjectTemplate.grade file
3. Update classpath `com.android.tools.build:gradle:3.4.0` to classpath `com.android.tools.build:gradle:3.4.3`
:::

\##Setup

1. In Unity go to **Build Settings** -> **Player Settings** -> **Android** -> **Publishing Settings** -> Enable **Custom Main Manifest** and **Custom Main Gradle Template** under the **Build** section
2. Open the newly generated `Assets/Plugins/Android/AndroidManifest.xml` file. Add the following code inside the `<application>` element:

```xml
<activity
  android:name="com.openfort.unity.RedirectActivity"
  android:exported="true" >
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="mygame" android:host="mobile-wallet-protocol" />
  </intent-filter>
</activity>
```

:::warning
Make sure that `android:scheme` **mygame** is the same as `Custom Scheme` (**mygame://** in this case)
:::

3. Open the newly generated `Assets/Plugins/Android/mainTemplate.gradle` file. Add the following code inside `dependencies` block:

```gradle
implementation('androidx.browser:browser:1.5.0')
```

:::info
For this version of the Chrome Custom Tabs to work, the compileSdkVersion must be at least 33. This is usually the same value as the targetSdkVersion, which you can set in **Build Settings** -> **Player Settings** -> **Android** -> **Other Settings** -> **Target API Level**.
:::

**Proguard**

If you enable **Minify** in your project settings, you will need to add a custom Proguard file to your project.

1. In Unity go to **Build Settings** -> **Player Settings** -> **Android** -> **Publishing Settings** -> Enable **Custom Proguard File** under the **Build** section
2. Open the newly generated Assets/Plugins/Android/proguard-user.txt file. Add the following code inside the `<application>` element

```txt
-dontwarn com.openfort.**
-keep class com.openfort.** { *; }
-keep interface com.openfort.** { *; }

-dontwarn androidx.**
-keep class androidx.** { *; }
-keep interface androidx.** { *; }
```


## Unity WebGL

:::info
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

This guide will walk you through adding support for any **global wallet** into a Unity app by integrating the [Mobile Wallet Protocol](https://mobilewalletprotocol.github.io/wallet-mobile-sdk/).

When doing `Build And Run` from your Unity **Build Settings** with the target platform `WebGL` you will notice that no popups are allowed. This is due to the `Cross-Origin-Opener-Policy` header being set to `same-origin-allow-popups` by default. This is a security feature to prevent popups from different origins.

There are two main things to consider when running your Unity WebGL build with global wallet support:

1. For any global wallet to work, you need to host the build or run it locally with `Cross-Origin-Opener-Policy` set to `same-origin-allow-popups`.
2. Compression Format: Set to Disabled (Player Settings > Publishing Settings) for final builds.

Here's an example setup for testing your global wallet locally using express server. Please note that in this example, the build output is in the `build-output` directory.
Once your build is done, follow these steps:

:::steps
#### 1. Create a Project Folder and Setup Files

Create a new folder for your server project and navigate to it:

```bash
mkdir unity-webgl-server
cd unity-webgl-server
```

Create a new subfolder called `build-output` where you'll place your Unity WebGL build files:

```bash
mkdir build-output
```

Copy all the files from your Unity WebGL build into the `build-output` folder. This should include files like:

* `index.html`
* `.unityweb` files
* Other assets and build files

#### 2. Initialize Your Node.js Project

Initialize a new Node.js project and install Express:

```bash
npm init -y
npm install express
```

Create a new file called `server.js` in the root folder with the following content:

```js server.js
const express = require("express");
const path = require("path");

const app = express();
const port = 8000;
 
app.use((req, res, next) => {
  res.header(
    "Cross-Origin-Opener-Policy",
    "same-origin-allow-popups",
  );
  next();
});
 
app.use(express.static(path.join(__dirname, "build-output")));
app.listen(port, () =>
  console.log(`Server running on http://localhost:${port}`),
);
```

```json package.json
{
  "name": "express-webgl",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.21.2"
  }
}
```

#### 3. Run Your Local Server

Start your Express server by running:

```bash
node server.js
```

You should see the message: `Server running on http://localhost:8000`

Open your browser and navigate to `http://localhost:8000` to see your Unity WebGL build running with global wallet support enabled.
:::

### Troubleshooting

If you encounter any issues:

1. Make sure your `build-output` folder contains all the necessary Unity WebGL build files
2. Confirm that your server is properly setting the `Cross-Origin-Opener-Policy` header
3. Check browser console for any errors
4. Ensure your global wallet is properly configured to work with the Mobile Wallet Protocol


## Create a game in Unity

:::note[Caution]
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

This guide will walk you through adding support for any **global wallet** into a Unity app by integrating the [Mobile Wallet Protocol](https://mobilewalletprotocol.github.io/wallet-mobile-sdk/).

:::note[TARGET PLATFORM VS UNITY EDITOR PLATFORM]
We have added compilation flags to the Unity SDK to ensure that specific Unity editors can only build certain platform targets. Please note that the table below indicates which editor you can use to build a platform target, but it does not determine whether you can run the SDK in that editor.

For example, the SDK allows you to build iOS games using a macOS Unity Editor, but you cannot use the Windows Unity Editor.

| Target Platform                                                | Windows Unity Editor | macOS Unity Editor |
| -------------------------------------------------------------- | :------------------: | :----------------: |
| Windows                                                        |           ✅          |          ❌         |
| macOS                                                          |           ❌          |          ✅         |
| [Android](/docs/products/cross-app-wallet/usage/unity-android) |           ✅          |          ✅         |
| iOS                                                            |           ❌          |          ✅         |
| [Web](/docs/products/cross-app-wallet/usage/unity-webgl)       |           ✅          |          ✅         |
:::

:::tip
If you need a template or scaffold to start with, you can check out the [Global Wallet Unity Example](https://github.com/openfort-xyz/mobile-wallet-protocol-unity-client/tree/main/Project).
:::

### Setup

#### Install Mobile Wallet Protocol Client

There are two ways to install the SDK:

##### UPM

1. Open the Package Manager
2. Click the add + button and select "Add package from git URL..."
   Enter [https://github.com/openfort-xyz/mobile-wallet-protocol-unity-client.git?path=com.openfort.mobile-wallet-protocol](https://github.com/openfort-xyz/mobile-wallet-protocol-unity-client.git?path=com.openfort.mobile-wallet-protocol) and click 'Add'

##### manifest.json

1. Open your project's Packages/manifest.json file
2. Add "com.openfort.mobile-wallet-protocol": "[https://github.com/openfort-xyz/mobile-wallet-protocol-unity-client.git?path=com.openfort.mobile-wallet-protocol](https://github.com/openfort-xyz/mobile-wallet-protocol-unity-client.git?path=com.openfort.mobile-wallet-protocol)" in the dependencies block

### Usage

Mobile Wallet Protocol Client provides an interface for Unity to interact with the Global Wallet, an EIP-1193 compliant provider interface.

The EIP-1193 provider implements a method called `request` that accepts an object with the following fields:

* **`method`**: the name of a JSON-RPC request to send to the wallet
* **`params`**: any parameters to include with the request

#### Methods

| Method                   | Function Name          |
| ------------------------ | ---------------------- |
| eth\_requestAccounts     | EthRequestAccounts     |
| eth\_sendTransaction     | EthSendTransaction     |
| personal\_sign           | PersonalSign           |
| eth\_signTypedData\_v4   | EthSignTypedDataV4     |
| wallet\_sendCalls        | WalletSendCalls        |
| wallet\_showCallsStatus  | WalletShowCallsStatus  |
| wallet\_grantPermissions | WalletGrantPermissions |
| wallet\_getCapabilities  | WalletGetCapabilities  |

#### EIP-1193 Provider

Create a new `EIP1193Provider` instance, which is EIP-1193 compliant.

```cs ClientController.cs
using UnityEngine;
using MobileWalletProtocol;

public class ClientController : MonoBehaviour
{
    [SerializeField]
    MWPClientOptions m_Options = new MWPClientOptions()
    {
        Metadata = new AppMetadata()
        {
            Name = "Smart Wallet",
            CustomScheme = "exp://",
            ChainIds = new string[] { "0xaa36a7" }
        },
        Wallet = Wallet.CreateWebWallet(
            name: "Rapid fire wallet",
            // The scheme should be the target wallet's URL
            scheme: "https://id.sample.openfort.io#policy=pol_a909d815-9b6c-40b2-9f6c-e93505281137",
            iconUrl: "https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV"
        )
    };

    MWPClient m_Client;
    string m_Account;

    void Awake()
    {
        m_Client = new MWPClient(m_Options);
    }

    public async void RequestAccounts()
    {
        var result = await m_Client.EthRequestAccounts();

        if (result.IsSuccess)
        {
            var accounts = result.Value;

            m_Account = accounts[0];

            foreach (var account in accounts)
            {
                Debug.Log("Account: " + account);
            }
        }
        else
        {
            Debug.LogError("Error: " + result.Error);
        }
    }

    public void Disconnect()
    {
        m_Client.Reset();
    }
}
```

### Gas Sponsorship

If you want to sponsor transactions, you need to add `#policy=POLICY_ID` to the wallet scheme.

```
#policy=POLICY_ID
```

### Troubleshooting

1. If no network appears in your wallet transaction request, make sure you:
   * Have the correct chain ID in the metadata
   * That chain is supported by your global wallet.


## Wagmi template to create a web app

The following is a quick and easy implementation for getting started with [Wagmi](https://wagmi.sh/) template and the global wallet of choice.

:::warning
To make these instructions concrete, we have created a sample global wallet called **Rapidfire ID**. To interact with it, you can find its SDK in the NPM package directory: [@rapidfire/id](https://www.npmjs.com/package/@rapidfire/id).

You can check out the GitHub [repository for Rapidfire Wallet](https://github.com/openfort-xyz/ecosystem-sample) to learn how to create your own wallet.
:::

This guide will walk you through integrating the global wallet Rapidfire ID.

:::tip
If you need a template or scaffold to start with, you can check out the [Rapidfire Wagmi Example](https://github.com/openfort-xyz/ecosystem-sample/tree/main/usage-examples/wagmi-nextjs).
:::

::::steps
#### Create a new Wagmi project

Run the project creation command using your preferred package manager and follow the CLI prompts to set up your project.

```bash terminal
npm create wagmi
```

#### Install dependencies and start development server

Install all required dependencies, start the development server. Your app should now be running on localhost.

```bash terminal
npm install @rapidfire/id
npm install
npm run dev
```

#### Configure Wagmi with Smart Wallet

Update the Wagmi configuration file, set up `polygonAmoy` as the primary chain, and configure wallet connector with injected wallet preference.

```ts wagmi.ts
import { http, createConfig } from 'wagmi';
import { polygonAmoy } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [polygonAmoy],
  connectors: [
    injected(),
  ],
  transports: {
    [polygonAmoy.id]: http(),
  },
});

declare module 'wagmi' {
  interface Register {
    config: typeof config;
  }
}
```

#### Wrap App in Context Provider

Wrap your app in the `WagmiProvider` React Context Provider and pass the **config** you created earlier to the **value** property.

:::code-group
```tsx [app.tsx]
import { WagmiProvider } from 'wagmi'
import { config } from './config'

function App() {
  useEffect(() => {
    config.getEthereumProvider();
  }, []);
  return (
    <WagmiProvider config={config}>
      {/** ... */}
    </WagmiProvider>
  )
}
```

```ts [config.ts]
import EcosystemWallet from '@rapidfire/id'

// Initialize the SDK with required parameters
export const config = new EcosystemWallet({
  appChainIds: [84532],
  appLogoUrl: 'https://a.rgbimg.com/users/b/ba/barunpatro/600/mf6B5Gq.jpg',
  appName: 'Example App',
});
```
:::

#### Keep building

You can find everything you need here: [https://wagmi.sh/react/api/hooks](https://wagmi.sh/react/api/hooks)
::::


## Authentication

At a high-level, onboarding users onchain breaks down into three core questions: who is taking the onchain action (the user), through what means are they able to control this action (the signer) and where is the affected state (the account).

**With Openfort, your app can authenticate users across web2 and web3 accounts, including:**

* **Email**, via password recovery
* **Wallet**: via Sign In With Ethereum ([SIWE](https://eips.ethereum.org/EIPS/eip-4361)) standard
* **Web2 social accounts**: via [OAuth2.0 Protocol](https://oauth.net/2/) (Google, Facebook, Twitter, Discord & more.)

These methods can be configured as either login or [link](/docs/products/embedded-wallet/javascript/auth/user-management) options for users. Once authenticated, Openfort creates a common player object that includes the user's ID (`playerID`) and all linked accounts, treating all users equally regardless of their authentication method.

The Openfort Auth can be plugged into any front-end/user interface you already have.

#### Guides

##### [Authenticating with email](/docs/products/embedded-wallet/javascript/auth/password)

Learn how to authenticate users with email.

##### [Non-custodial signer](/docs/products/embedded-wallet/javascript/signer/recovery)

Create a non-custodial signer for your users.

##### [Session keys](/docs/products/embedded-wallet/javascript/smart-wallet/advanced/session-keys)

Create session keys with smart wallets

#### Templates

##### [Auth with NextJS](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample)

Openfort comlete sample solution for NextJS.

##### [Auth with Web3Auth](https://github.com/openfort-xyz/samples/tree/main/web3auth-nextjs)

Integration with an external signer like Web3Auth.

##### [Auth with Firebase](hhttps://github.com/openfort-xyz/embedded-wallet-firebase-auth-sample-nextjs)

Integration with thirdparty auth proividers like Firebase.


## FAQs

#### What is an embedded wallet?

An embedded wallet is a in-app wallet designed to onboard both web2 and web3 users simultaneously. Nexus includes several core components:

* Authentication: A single-sign on authentication experience with familiar social logins
* Wallet: An embedded wallet accessible across all devices and games
* Account: The asset layer, powering users onchain to manage their assets

#### How is an embedded wallet different to existing web3 wallets?

Unlike browser extension wallets like MetaMask, which can be challenging for users to set up, or "embedded wallet" that are limited to a single application, Openfort Identity offers a balance of user-friendliness and versatility.
Openfort Identity allows users to use the same wallet across all their games and marketplaces, rather than having one wallet per game.

#### How does an embedded wallet's key management work?

Openfort uses a smart contract wallet system on EVM chains. Transactions are processed only if they're signed by either the player (embedded wallet) or the game (session key).

* Private key: Using an SSS approach to split the key in three shards only to be reconstructed on the player's client side.
* Session key: Temporary key used created by the player authorizing a third party to make transactions under a scooped permission set.

#### What platforms does embedded wallet support?

|  Functionality | Web | Unity | Unreal | PlayStation | Xbox |
| :------------: | :-: | :---: | :----: | :---------: | :--: |
| Authentication | Yes |  Yes  |   Yes  |      No     |  No  |
|  Transactions  | Yes |  Yes  |   Yes  |      No     |  No  |

#### What types of providers does authentication support?

Openfort supports familiar social logins and passwordless email sign-in. You can also import a custom auth token or a OIDC compatible token.

#### Can users export their wallet private keys?

Yes, you can use the endpoints provide to [export the private key](/docs/products/embedded-wallet/javascript/signer/export-key).

#### How does wallet recovery work with Openfort?

With Openfort you can recover the account if you forget your email/social login as long as you have a majority of 2/3 key shards.

In the event of not having the majority of shards, we've implemented a [social recovery](/docs/products/embedded-wallet/javascript/smart-wallet/advanced/social-recovery) where the private key can be reconstructed.

#### Can a user change their associated email address for a pre-generated wallet?

No, a user cannot change their email address once they have created a pre-generated wallet. If they need to change their email address, they will need to create a new wallet.

#### How will embedded wallets integrate with existing authentication or account systems?

**Option 1: Full Authentication & Signer.** If you're starting from scratch, a very common way to use Nexus is as your game's primary identity and wallet (as games like Rogue Nation do).

**Option 2: Existing Authentication & Signer.** However, many games will already have an account system that they will be reluctant to migrate away from. Easy solution, integrate your authentication with Nexus while using the signer solution.

**Option 3: Existing Authentication & Existing Signer.** You might be already using a wallet provider and want to upgrade to smart accounts.

#### What level of support and Service Level Agreements (SLAs) are provided?

At Openfort, we understand the significance of maintaining a high standard of service. Our Service Level Agreements (SLAs) reflect our commitment to providing a reliable, efficient, and safe environment for your operations.

### Security and Contingency Planning

#### If Openfort were to shut down with a one-month notice, would there be scope to change the signer on the Smart Contract Wallet and use it in connection with a different provider that manages the private keys differently?

**TLDR:** With enough time, transitioning is fairly simple. You'd need to invoke the `transferOwnership` function for users to accept the new signer.

**Detailed Answer:** Yes, if Openfort shuts down with a one-month notice, it's possible to change the signer. Since Openfort wallets are non-custodial, users have control over their private keys. The key migration process would involve using the "recovery share" and "device share" from Shamir's Secret Sharing (SSS) to reconstruct the private key, allowing users to accept a new signer through the `transferOwnership` function. The new provider would need to support compatible key management systems.

#### If Openfort were shut down with zero notice, would there be any scope to do a migration? Would that rely on a self-hosted Shield for the recovery share and the device share being intact?

**TLDR:** If there is no self-hosted option, users should rely on on-chain social recovery.

**Detailed Answer:** Migration is still possible, but it depends on the self-hosted Shield for the recovery share and the availability of the device share. If a self-hosted Shield is not in place, users can utilize on-chain social recovery. As long as the device share and recovery share are intact, users can reconstruct their private key and migrate to a new provider. On-chain social recovery can also help recover the wallet if the device share is lost.

#### If Openfort's API were compromised, what is the risk there? Can that risk be mitigated? What's the risk of the auth share on the private key being exposed?

**TLDR:** Both Openfort's server and Shield are encrypted. Even if an attacker obtains the auth share, they would need a secret to decrypt it.

**Detailed Answer:** If Openfort's API were compromised, the risk is limited because both the auth share and Shield service are encrypted. Even if an attacker gains access to the auth share, they would still need to decrypt it using a secret. Furthermore, since the private key is split using Shamir's Secret Sharing, the auth share alone is insufficient to reconstruct the full key without the device or recovery share.


## Overview Javascript

The [Openfort Javascript SDK](https://github.com/openfort-xyz/openfort-js) is a Javascript library client for Openfort that allows you to add secure authentication, non-custodial embedded wallets, and powerful UX infrastructure into your game.

### Features

| Feature                                   | Status |
| ----------------------------------------- | ------ |
| Sign in with email                        | ✅      |
| Sign in with OAuth                        | ✅      |
| Sign in with guest mode                   | ✅      |
| Sign in with Third-Party Auth             | ✅      |
| Embedded wallet creation                  | ✅      |
| Embedded wallet recovery                  | ✅      |
| Embedded wallet signatures & transactions | ✅      |
| Native smart wallets                      | ✅      |
| Gas sponsorship                           | ✅      |
| Session keys                              | ✅      |

:::info
This section is **completely headless (no UI)**, if you're looking to add authentication UI and wallet connectors please head to [Openfort Kit](/docs/products/embedded-wallet/react/kit).
:::

### Get started

Check out these popular guides to get started.

#### [Setting up the SDK](/docs/products/embedded-wallet/javascript/quickstart)

Setting up a project

#### [Smart wallets](/docs/products/embedded-wallet/javascript/smart-wallet)

Using smart wallets

#### [Embedded wallet](/docs/products/embedded-wallet/javascript/signer/recovery)

Create an embedded wallet

### Templates

Check out these popular samples to get started.

#### [Auth Sample](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample)

Use the next-app starter sample

#### [Solana sample](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/solana-sample)

Create a Solana wallet

#### [Vue sample](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/wallet-libraries/vite-wagmi)

Wagmi + Openfort + Vue


## Quickstart

**The [Openfort JS SDK](https://www.npmjs.com/package/@openfort/openfort-js) is a low level library that allows you to build custom login flows, request signatures and more.**

<div className="tip">
  **Want to start building right away?**

  If you're looking to quickly build with auth UI elements into your app, check out our [React](/docs/products/embedded-wallet/react/kit) guides.
</div>

You will get out of the box support for:

1. Multiple authentication methods
2. Bare-metal API access to customize your own UI
3. Non-custodial embedded wallet
4. Account abstraction compatible and infrastructure

Check out the [starter repos](/docs/overview/repositories) for templates for integrating Openfort with various libaries, frameworks and use cases.

::::steps
### Install the Openfort SDK

Install the latest version of the [Openfort JS SDK](https://www.npmjs.com/package/@openfort/openfort-js) using your package manager of choice:

:::note
**Prerequisites**

In order to integrate Openfort, you project must:

* a **Node v20** (Active LTS version) or **higher**.
* a [minimum TypeScript version of 5](https://github.com/microsoft/TypeScript/releases/tag/v5.0.2)
:::

:::code-group
```sh [npm]
npm install @openfort/openfort-js@latest
```

```sh [yarn]
yarn add @openfort/openfort-js@latest
```

```sh [pnpm]
pnpm install @openfort/openfort-js@latest
```
:::

### Set your auth providers

Navigate to the **auth providers** page on the [Openfort dashboard](https://dashboard.openfort.io) by selecting your project and then clicking Auth providers Methods in the side bar in the [players page](https://dashboard.openfort.io/players). Select the account types you'd like users to be able to login with. For more information on how to enable social logins, check out the [dashboard docs](/docs/configuration/social-login).

### Get your [API keys](/docs/configuration/api-keys)

In the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) section, you'll find:

* **Publishable Key**: Safe to expose in client-side environment
* **Secret Key**: Must be kept secure and used only server-side

To generate non-custodial wallets:

1. Scroll to the Shield section and click **Create Shield keys**
2. **Store the encryption share** safely when it appears (you'll only see it once)
3. You'll receive:
   * **Shield Publishable Key**: Safe for client-side use
   * **Shield Secret Key**: Keep secure, server-side only

### Import Openfort into your app

In your project, import the Openfort and configure it. Set the publishable keys fields to the publishable key you got from the Dashboard in step 3.

Concretely, the Openfort SDK needs to be instantiated only once.

```ts server.ts
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  }
});
```

### You're good to go!

Once you've configured your app, you can now use `openfort` throughout to access the Openfort SDK.

Check out our [starter repo](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample) to see what a simple end-to-end integration looks like, or read on to learn how you can use Openfort to:

* [Log your users in](/docs/products/embedded-wallet/javascript/auth).
* [Request signatures](/docs/products/embedded-wallet/javascript/smart-wallet).
::::


## JavaScript SDK Troubleshooting

### Vite Build Errors

#### Q: I'm getting warnings like "Module "buffer" has been externalized for browser compatibility" when building with Vite. How do I fix this?

A: This issue is caused by missing Node polyfills in your bundled web application. To resolve it:

1. Install `vite-plugin-node-polyfills`:
   ```bash
   npm i --save-dev vite-plugin-node-polyfills
   # or
   yarn add --dev vite-plugin-node-polyfills
   ```

2. Update your `vite.config.js` or `vite.config.ts`:
   ```javascript
   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   import { nodePolyfills } from 'vite-plugin-node-polyfills'

   export default defineConfig({
     plugins: [
       react(), 
       nodePolyfills()
     ],
   })
   ```

3. Restart your development server.

#### Q: I'm getting a "Cannot read properties of undefined (reading 'from')" error in hdkey-without-crypto.js. How do I fix this?

A: This error is related to the `ethereum-cryptography` package. To fix it:

1. Install the `buffer` package:
   ```bash
   npm install buffer
   # or
   yarn add buffer
   ```

2. Update your `vite.config.ts`:
   ```javascript
   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   import { nodePolyfills } from 'vite-plugin-node-polyfills'

   export default defineConfig({
     plugins: [
       react(),
       nodePolyfills({
         globals: {
           Buffer: false
         }
       })
     ],
     define: { 
       global: {},
     },
   })
   ```

3. Restart your Vite dev server.

#### Q: I'm getting a "require is not defined" error when using `vite preview`. How do I fix this?

A: Add the following to your `vite.config.ts` file:

```javascript
export default defineConfig({
  // ... your existing config
  build: {
    commonjsOptions: {
      transformMixedEsModules: true
    }
  },
})
```

Then rebuild your project before running `vite preview`.

### Webpack Build Errors

#### Q: I'm getting "Module not found" errors for Node.js core modules when using create-react-app. How do I fix this?

A: This is due to Webpack 5 not including Node.js polyfills by default. To fix it:

1. Install required packages:
   ```bash
   npm install --save-dev react-app-rewired crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process
   # or
   yarn add --dev react-app-rewired crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process
   ```

2. Create a `config-overrides.js` file in your project root:
   ```javascript
   const webpack = require('webpack');
   module.exports = function override(config) {
     const fallback = config.resolve.fallback || {};
     Object.assign(fallback, {
       crypto: require.resolve('crypto-browserify'),
       stream: require.resolve('stream-browserify'),
       assert: require.resolve('assert'),
       http: require.resolve('stream-http'),
       https: require.resolve('https-browserify'),
       os: require.resolve('os-browserify'),
       url: require.resolve('url'),
     });
     config.resolve.fallback = fallback;
     config.plugins = (config.plugins || []).concat([
       new webpack.ProvidePlugin({
         process: 'process/browser',
         Buffer: ['buffer', 'Buffer'],
       }),
     ]);
     config.module.rules.push({
       test: /\.m?js/,
       resolve: {
         fullySpecified: false,
       },
     });
     return config;
   };
   ```

3. Update your `package.json` scripts:
   ```json
   "scripts": {
     "start": "react-app-rewired start",
     "build": "react-app-rewired build",
     "test": "react-app-rewired test",
     "eject": "react-scripts eject"
   }
   ```

#### Q: How do I deal with 'failed to parse source map' warnings?

A: You can disable these warnings by adding `GENERATE_SOURCEMAP=false` to your start script in `package.json`:

```json
"scripts": {
    "start": "GENERATE_SOURCEMAP=false react-app-rewired start",
    // ...
},
```

### Next.js Build Errors

#### Q: I'm getting a "Named export 'curves' not found" error with the elliptic package in Next.js 13/14. How do I fix this?

A: Add the following to your `next.config.js`:

```javascript
const nextConfig = {
  // ... other next config
  experimental: {
    esmExternals: false,
  },
};
```

#### Q: I'm having issues importing SDK modules in Next.js 13 with the App Router. What should I do?

A: Use the SDK Code Splitting method for imports:

```typescript
import Openfort from '@openfort/openfort-js';
```

#### Q: I'm getting a "Cannot read properties of undefined (reading 'fromMasterSeed')" error in Next.js 12. How do I fix this?

A: Add the following to your `next.config.js`:

```javascript
const nextConfig = {
  // ... other next config
  experimental: {
    esmExternals: false,
  },
};
```

#### Q: I'm getting a "Could not detect network" error on Next.js 14 API endpoint with JsonRpcProvider. How do I fix this?

A: You have three options:

1. Downgrade to Next.js 13
2. Upgrade to Ethers v6
3. Use the solution provided [in this GitHub issue discussion](https://github.com/ethers-io/ethers.js/issues/3952#issuecomment-1698913553)


## Using the JS SDKs

There are **two** steps to configure Openfort's embedded wallets in your application:

* Configure the embedded wallet configuration.
* Wait for the signer to be ready.

### Embedded wallet configuration

The Openfort SDKs provide a way to configure a non-custodial embedded wallet that can be used to sign transactions and interact with the blockchain.
The **`configureEmbeddedSigner`** is the method responsible for setting up and creating the non-custodial wallet.

:::code-group
```ts [config.ts]
import { ShieldAuthType, RecoveryMethod } from "@openfort/openfort-js";
import openfort from "./openfortConfig";

// This example assumes that the user is `authenticated`
async function configure(password: string, auth_token: string) {
  const chainId = 80002;
  const shieldAuthentication = {
    auth: ShieldAuthType.OPENFORT,
    token: auth_token,
  };
  const recoveryParams = {
    password: password,
    recoveryMethod: RecoveryMethod.PASSWORD,
  };
  await openfort.embeddedWallet.configure({
    chainId,
    shieldAuthentication,
    recoveryParams,
  });
}
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    shieldEncryptionKey: "YOUR_SHIELD_ENCRYPTION_SHARE",
  },
});

export default openfort;
```
:::

The `configureEmbeddedSigner` will include a `chainID` parameter, which is the identifier of the blockchain network you want to interact with and create an embedded wallet there. You can read the list of supported chains [here](/docs/configuration/chains).

Let's go over the rest of the `shieldAuth` parameters of the `configureEmbeddedSigner` method:

| Parameter | Description                                                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth      | Defines how the `token` parameter is going to be verified. Can be either **openfort** or **custom**, defining if the token is going to be verified by Openfort or by another backend. |
| token     | The `access_token` or `id_token` that will be used to verify that the user is logged in in your application.                                                                          |

:::tip
**Automatic embedded wallet creation**: to offer a frictionless onboarding, enable automatic embedded wallet creation. Learn more about it [how to enable automatic recovery](/docs/products/embedded-wallet/javascript/signer/recovery).
:::

### Waiting for ready

When calling `configureEmbeddedSigner`, the SDK will go through a series of states before it is ready to be used. These states are represented by the enum:

| State                                      | Description                                                            |
| ------------------------------------------ | ---------------------------------------------------------------------- |
| **0** - NONE                               | The initial state of the SDK.                                          |
| **1** - UNAUTHENTICATED                    | Before the user is authenticated.                                      |
| **2** - EMBEDDED\_SIGINER\_NOT\_CONFIGURED | Before calling the `configureEmbeddedSigner`.                          |
| **3** - CREATING\_ACCOUNT                  | If no account exists for the current chainID, when it will be created. |
| **4** - READY                              | The embedded wallet is ready to be used                                |

**As a consequence, it's important to wait until the `embeddedState` has finished initializing before you use the embedded wallet**, to ensure that the state you consume is accurate and not stale.

To determine whether the Openfort SDK has initialized the embedded wallet, you can call the method `getEmbeddedState` and check if the state is `READY`:

:::code-group
```ts [main.ts]
import openfort from "./openfortConfig";

const state = openfort.embeddedWallet.getEmbeddedState();
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::


## Understanding Wallets

### Embedded wallet

A **private key is a signer**—a cryptographic entity capable of signing messages and transactions on behalf of a user. When this private key is created and managed within an app or game, it becomes what we call an **embedded wallet**.

At Openfort, embedded wallets are self-custodial by design. These wallets are seamlessly integrated into your application and don't require an external wallet client like a browser extension or mobile app. This makes them ideal for users who don't already have a wallet or prefer not to connect an external one.

You can choose exactly when to provision an embedded wallets for your user and can interact with it through Openfort's signature and transaction APIs, or through libraries like `wagmi`, `viem`, or any other tooling that supports the EIP-1193 provider interface.

### Wallet types: EOAs and Smart Accounts

In the context of blockchains, there are two main types of wallets:

* **Externally Owned Accounts (EOAs)**: These are the standard accounts controlled directly by a private key. EOAs are simple and efficient, but limited in terms of programmability.

* **Smart Accounts (aka Smart Wallets)**: These are onchain smart contracts that implement advanced logic for how assets are managed and transactions are authorized.

Every embedded wallet created by Openfort is paired with a **smart wallet**, offering users a modern, programmable onchain experience from day one.

### Smart wallets and ERC-4337

Smart wallets provisioned through Openfort are [ERC-4337-compatible](https://www.erc4337.io/) smart contract accounts. This means they support **account abstraction**—a standard that enables:

* **Gas sponsorship** via paymasters
* **Transaction batching** and session signing
* **Permission delegation** and modular wallet logic

ERC-4337 introduces a new infrastructure layer—**entry points, bundlers, and paymasters**—which abstracts complex wallet logic from the base protocol, allowing for highly customizable, user-friendly wallets.

With Openfort, you don't need to manage any of this infrastructure manually. We handle signer creation, smart wallet deployment, and integration with the ERC-4337 stack automatically.

### EOAs + ERC-7702: Upgrading the basic wallet

Thanks to the new [ERC-7702](https://eips.ethereum.org/EIPS/eip-7702) standard, EOAs can now be **temporarily upgraded into smart EOAs**, enabling many of the same benefits as smart wallets—including:

* Gasless transactions
* Batching
* Custom validation logic

The key difference is that with ERC-7702, the EOA remains in control and no smart contract is permanently deployed. However, **key rotation is not supported** under 7702, unlike fully programmable smart wallets.

### JavaScript Implementation

In JavaScript applications, you can interact with embedded wallets through Openfort's signature and transaction APIs, or through popular web3 libraries that support the EIP-1193 provider interface.

```typescript
import { Openfort } from '@openfort/openfort-js'

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_PUBLISHABLE_KEY"
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY"
  }
})

// Get EIP-1193 provider for web3 library integration
const provider = await openfort.embeddedWallet.getEthereumProvider()
```

### Browser-Specific Features

JavaScript embedded wallets in web browsers provide several unique capabilities:

#### EIP-1193 Provider Interface

Direct access to the standard Ethereum provider interface for seamless integration with existing web3 tooling.

```typescript
// Use with any EIP-1193 compatible library
const accounts = await provider.request({ method: 'eth_accounts' })
const chainId = await provider.request({ method: 'eth_chainId' })
```

#### Web3 Library Integration

Seamless integration with popular web3 libraries:

* **Wagmi**: React hooks for Ethereum
* **Viem**: TypeScript interface for Ethereum
* **Ethers**: Complete Ethereum library

```typescript
// Example with Viem
import { createWalletClient, custom } from 'viem'

const walletClient = createWalletClient({
  transport: custom(provider)
})
```


## React SDK

We are excited to announce the **React SDK** for Openfort Embedded Wallet, which allows you to easily integrate Openfort's wallet solutions into your React applications. This SDK provides a simple and efficient way to manage user authentication, wallet interactions, and blockchain transactions.

### 🚧 Work in progress 🚧

Stay tuned for updates as we continue to enhance the SDK with new features and improvements.

As for now, you can use the [JavaScript SDK](/docs/products/embedded-wallet/javascript) to integrate Openfort's wallet solutions into your React applications. The JavaScript SDK is fully compatible with React and provides all the necessary functionalities to manage user authentication, wallet interactions, and blockchain transactions.


## Build with React Native

::::steps
### Install Required Dependencies

Install the latest version of the [Openfort React Native SDK](https://www.npmjs.com/package/@openfort/react-native) and its required dependencies:

```sh [terminal]
# Install Openfort React Native SDK
yarn add @openfort/react-native @openfort/openfort-js

# Install required dependencies
yarn add buffer react-native-crypto react-native-get-random-values react-native-randombytes stream-browserify react-native-mmkv
```

### Configure Metro

Create or update your `metro.config.js` to include the necessary Node.js module shims:

```javascript
// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

module.exports = (() => {
  const config = getDefaultConfig(__dirname);

  // Add shims for Node.js modules
  config.resolver.extraNodeModules = {
    crypto: require.resolve('react-native-crypto'),
    stream: require.resolve('stream-browserify'),
    buffer: require.resolve('buffer'),
  };

  return config;
})();
```

### Set up auth providers

Navigate to the **auth providers** page on the [Openfort dashboard](https://dashboard.openfort.io) by selecting your project and clicking Auth Providers Methods in the side bar in the [players page](https://dashboard.openfort.io/players). Select the account types you'd like users to be able to login with.

### Get your Openfort keys

From the [Openfort Dashboard](https://dashboard.openfort.io), select your desired app and navigate to the [developers page](https://dashboard.openfort.io/developers/configuration/api-keys). You'll need:

* **Publishable Key**: Safe to expose in client-side environment
* **Secret Key**: Must be kept secure and used only server-side
* **Shield Keys**: Required for non-custodial wallets
  * Create Shield keys in the Shield section
  * Securely store the encryption share shown in the one-time popup
  * You'll get both a Publishable and Secret Shield key

### Configure your app

#### Import Polyfills

First, import the Openfort React Native polyfills at the top of your app:

```typescript
import "@openfort/react-native/polyfills";
```

#### Set up the WebView

Add the Safe area provider and hooks to your app's root layout:

```typescript
// app/_layout.tsx

import { Redirect, Slot } from "expo-router";
import React from "react";
import { ConsoleProvider } from "../hooks/useConsole";
import { OpenfortProvider } from "../hooks/useOpenfort";
import { SafeAreaProvider } from "react-native-safe-area-context";

export default function RootLayout() {

  return (
    <SafeAreaProvider>
      <ConsoleProvider>
        <OpenfortProvider>
          <Redirect href="/main" />
          <Slot />
        </OpenfortProvider>
      </ConsoleProvider>
    </SafeAreaProvider>
  );
}
```

#### Initialize Openfort

Configure the Openfort SDK with your keys:

```typescript
import { Openfort } from "@openfort/react-native";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  }
});
```

:::note[Important]
Because we use `mmkv` storage, expo-go will not work. Use `expo run:ios` or `expo run:android` to run your app.
:::
::::

### Next Steps

Now that you've configured your app, you can use `openfort` throughout to access the Openfort SDK. Check out our [starter repo](https://github.com/openfort-xyz/react-native-auth-sample) to see a complete integration.


## Overview Unity

The [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) is a Unity library client for Openfort that allows you to add secure authentication, non-custodial embedded wallets, and powerful UX infrastructure into your game.

### Features

| Feature                                   | Status |
| ----------------------------------------- | ------ |
| Sign in with email                        | ✅      |
| Sign in with OAuth                        | ✅      |
| Sign in with guest mode                   | ✅      |
| Sign in with Third-Party Auth             | ✅      |
| Embedded wallet creation                  | ✅      |
| Embedded wallet recovery                  | ✅      |
| Embedded wallet signatures & transactions | ✅      |
| Native smart wallets                      | ✅      |
| Gas sponsorship                           | ✅      |
| Session keys                              | ✅      |

### Supported platforms

* Windows (64-bit)
* macOS (minimum version 12.5)
* Android (minimum version 5.1)
* iOS (minimum version 15.2)

<div>
  **SUPPORTED UNITY VERSIONS**

  * Unity 2021.3 or newer for Windows, macOS, Android and iOS
  * Unity 2019.4 or newer for macOS, Android, and iOS. Windows isn't supported on Unity versions from 2019.4 up through 2021.2.
</div>

<div>
  **TARGET PLATFORM VS UNITY EDITOR PLATFORM**

  We have added compilation flags to the Unity SDK to ensure that specific Unity editors can only build certain platform targets. Please note that the table below indicates which editor you can use to build a platform target, but it does not determine whether you can run the SDK in that editor.

  For example, the SDK allows you to build iOS games using a macOS Unity Editor, but you cannot use the Windows Unity Editor.

  | Target Platform | Windows Unity Editor | macOS Unity Editor |
  | --------------- | :------------------: | :----------------: |
  | Windows         |           ✅          |          ❌         |
  | macOS           |           ❌          |          ✅         |
  | Android         |           ✅          |          ✅         |
  | iOS             |           ❌          |          ✅         |
  | Web             |           ✅          |          ✅         |
</div>

### Get started

Check out these popular guides to get started.

#### [Setting up the SDK](/docs/products/embedded-wallet/unity/quickstart)

Setting up and importing a project

#### [WebGL](/docs/products/embedded-wallet/unity/webgl)

Using embedded wallets with WebGL

#### [Embedded wallet](/docs/products/embedded-wallet/unity/signer/recovery)

Create an embedded wallet

### Templates

Check out these popular samples to get started.

#### [Unity Sample](https://github.com/openfort-xyz/openfort-csharp-unity/tree/main/sample)

Check our latest Unity sample


## Unity Quickstart

### Prerequisites

The Unity SDK requires:

* [UniTask](https://github.com/Cysharp/UniTask) package (version 2.3.3)
* Installation of git-lfs from [git-lfs.github.com](https://git-lfs.github.com/)

::::steps
### 1. Install the Openfort SDK

There are two ways to install the SDK:

#### UPM

Since .dll files are stored on Git Large File Storage, you must download and install git-lfs from [here](https://git-lfs.github.com/).

1. Open the Package Manager
2. Click the add + button and select "Add package from git URL..."
   Enter [https://github.com/openfort-xyz/openfort-csharp-unity.git?path=/src/Packages/OpenfortSDK](https://github.com/openfort-xyz/openfort-csharp-unity.git?path=/src/Packages/OpenfortSDK) and click 'Add'

#### manifest.json

Since .dll files are stored on Git Large File Storage, you must download and install git-lfs from [here](https://git-lfs.github.com/).

1. Open your project's Packages/manifest.json file
2. Add "com.openfort.sdk": "[https://github.com/openfort-xyz/openfort-csharp-unity.git?path=/src/Packages/OpenfortSDK](https://github.com/openfort-xyz/openfort-csharp-unity.git?path=/src/Packages/OpenfortSDK)" in the dependencies block

### 2. Set your auth providers

1. Navigate to the **auth providers** page on the [Openfort dashboard](https://dashboard.openfort.io)
2. Click Auth providers Methods in the side bar in the [players page](https://dashboard.openfort.io/players)
3. Configure the methods you want users to be able to login with

### 3. Get your [API keys](/docs/configuration/api-keys)

In the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) section, you'll find:

* **Publishable Key**: Safe to expose in client-side environment
* **Secret Key**: Must be kept secure and used only server-side

To generate non-custodial wallets:

1. Scroll to the Shield section and click **Create Shield keys**
2. **Store the encryption share** safely when it appears (you'll only see it once)
3. You'll receive:
   * **Shield Publishable Key**: Safe for client-side use
   * **Shield Secret Key**: Keep secure, server-side only

### 4. Initialize Openfort in your Unity project

Create a new script to manage the Openfort integration:

```csharp
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class OpenfortManager: MonoBehaviour {
    private OpenfortSDK openfort;
    const string PublishableKey = "YOUR_OPENFORT_PUBLISHABLE_KEY";
    const string ShieldApiKey = "YOUR_SHIELD_PUBLISHABLE_KEY";
    const string ShieldEncryptionShare = "YOUR_SHIELD_ENC_SHARE";
    
    private async void Start()
    {
        openfort = await OpenfortSDK.Init(PublishableKey, ShieldApiKey, ShieldEncryptionShare);
    }
}
```

:::tip
If you're developing for WebGL, check out the additional setup steps in the Unity WebGL documentation.
:::

### 5. You're ready to build!

With Openfort configured in your Unity project, you can now:

* [Implement user authentication](/docs/products/embedded-wallet/unity/auth/email)
* [Handle signatures](/docs/products/embedded-wallet/unity/signer/sign-messages)

For a complete example of Openfort integration in Unity, check out our [sample projects](https://github.com/openfort-xyz/openfort-csharp-unity/tree/main/sample).
::::


## Unity SDK Troubleshooting

### Platform and Compatibility

#### Q: Can I test the SDK using the Unity Editor for Android and iOS?

A: Yes, you can test the SDK using the Unity Editor for Android and iOS on both Mac and Windows. However, be aware that:

* Native Android and iOS WebViews cannot run in the editor.
* The macOS WebView is used for the Mac Unity Editor.
* The Windows WebView is used for the Windows Unity Editor.

For the most accurate testing, we recommend using an actual device or emulator.

#### Q: Do you support IL2CPP for Windows?

A: Currently, we do not support IL2CPP on the Windows platform.

#### Q: I'm getting "Webview is not supported on this platform." How do I fix this?

A: This error suggests that the WebView is not properly set up for your target platform. Ensure that you've correctly installed and configured the WebView plugin for your specific platform. If the issue persists, check our documentation for platform-specific setup instructions.

### Installation and Setup

#### Q: I'm getting "The type or namespace name 'Shared' does not exist in the namespace 'VoltstroStudios.UnityWebBrowser' (are you missing an assembly reference?)". How do I fix this?

A: This error often occurs when large files like `.dll` are not properly downloaded. To resolve this:

1. Download and install git-lfs from [https://git-lfs.com/](https://git-lfs.com/)
2. Clone the repository again or pull the latest changes.

If the issue persists, ensure that all project dependencies are correctly installed and that your Unity version is compatible with the SDK.

### Authentication and Login

#### Q: Can I log in using a WebView instead of opening the browser?

A: The SDK primarily uses the system browser for authentication due to security considerations. However, if you have specific requirements for using a WebView, please contact our support team to discuss potential alternatives.

#### Q: Why is the in-app browser used for login on mobile and not a WebView?

A: The in-app browser is used for enhanced security, especially for single sign-on (SSO) purposes:

* It runs on a separate process from the hosting game, preventing the game from accessing or modifying its content.
* It's more resistant to malicious code injection.
* WebViews, in contrast, can be more easily controlled by the hosting game, making them potentially less secure for authentication processes.

#### Q: On iOS, when using AuthenticateWithOAuth login function, I get an alert asking: "\[My Game] Wants to Use 'openfort.sdk' to Sign in". Can I modify or remove this alert?

A: This alert is system-generated by iOS when using `ASWebAuthenticationSession` for secure authentication. Unfortunately, it cannot be removed or modified as it's triggered by the operating system. You can find more information about this in the [Apple Developer Documentation](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).

### Functionality

#### Q: Can I use the Unity SDK for crafting (burn and mint) assets?

A: Yes, the SDK supports various blockchain operations, including minting and burning assets. For specific implementation details, please refer to our documentation on asset management or contact our support team for guidance.

### Troubleshooting

#### Q: I'm getting "TimeoutException: Exceed Timeout:00:01:00". What does this mean?

A: This exception occurs when a function call takes longer than the default timeout of one minute to return a response. To resolve this:

1. Check the bottom of the stack trace or logs to identify the specific function causing the timeout.
2. If needed, you can customize the timeout duration using the `SetCallTimeout` function.
3. Ensure your network connection is stable and that you're not experiencing unusually high latency.


## WebGL Setup

Openfort's Unity SDK leverages an iframe to secure the key material for a user's embedded wallet. Given the use of an iframe, we recommend testing builds with Openfort's Unity SDK in the browser, or on a non-WebGL platform in the Unity editor.

<div>
  Watch this [demo](https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer) of setting up the Openfort SDK in a Unity Project!
</div>

To configure settings for your WebGL build to work with Openfort, go to your Project Settings in the Unity editor. Next, select Player and navigate to WebGL. Set the following values:

* **In Resolution and Presentation**, select `openfort`.

<div align="center">
  <img alt="unity-webgl-template" src="https://blog-cms.openfort.io/uploads/webgl_template_3147c927c2.png" width="80%" height="80%" />
</div>

* In **Other Settings/Optimization, managed stripping level** to **minimal**

<div align="center">
  <img alt="unity-stripping" src="https://blog-cms.openfort.io/uploads/stripping_unity_c848e1df33.png" width="80%" height="80%" />
</div>


## Backend wallets

Backend wallets are externally-owned accounts that your application controls to manage on-chain operations. They act as trusted intermediaries that can handle various automated tasks and workflows in your application.

:::tip
As a developer, you can also use smart wallet as a backend wallet (some benefits include the batching of transactions), please refer to our guide on how to create [smart wallets](/docs/products/embedded-wallet/javascript/smart-wallet) and use as backend wallets.
:::

### Why use backend wallets?

Backend wallets enable your application to:

* Automate onchain operations and signatures
* Manage transactions programmatically
* Handle user interactions on behalf of the user
* Control asset or token distribution and inventory


## Using backend wallets

### Create wallet

Backend wallets can be created through our dashboard or API. You can either create a new wallet or add an existing one.

#### Using the Dashboard

Navigate to the [Openfort dashboard](https://dashboard.openfort.io) and create a new developer account.

#### Using the API

You can create or add backend wallets through our API:

:::code-group
```ts [Node]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const settings = await openfort.settings.createDeveloperAccount()
```

```bash [curl]
curl https://api.openfort.io/v1/settings/developer_accounts \
  -u "$YOUR_SECRET_KEY:" \
  -d address="0x..." \
  -d signature="0x..." \
  -d name="My Backend Wallet"
```
:::

### Transactions

To execute a transaction from your backend wallet:

:::code-group
```ts [Node]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const transactionintents = await openfort.transactionIntents.create({
  account: 'dac_...', // Your backend wallet ID
  chainId: 80002,
  policy: 'pol_...', // Optional: Policy ID for gas sponsorship
  optimistic: true,
  interactions: {
    contract: 'con_....',
    functionName: 'transfer',
    functionArgs: ['recipient_address', 'amount']
  }
})
```

```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d 'account=dac_...' \
  -d optimistic=true \
  -d 'interactions[0][contract]=con_....' \
  -d 'interactions[0][functionName]=transfer' \
  -d 'interactions[0][functionArgs][0]=recipient_address' \
  -d 'interactions[0][functionArgs][1]=amount'
```
:::

:::info
For gas sponsorship, make sure to set up appropriate policies with account\_functions rules. Learn more about creating policy sponsors in the Openfort dashboard.
:::

#### Checking transaction status

You can monitor the status of transactions through our webhook system or by querying the API:

:::code-group
```ts [Node]
const transactionIntent = await openfort.transactionIntents.retrieve('tin_...');
console.log(transactionIntent.status);
```

```bash [curl]
curl https://api.openfort.io/v1/transaction_intents/tin_... \
  -u "$YOUR_SECRET_KEY:"
```
:::

### Common Use Cases

#### Minting NFTs with a backend wallet

In this example, we'll use a backend wallet to mint an NFT to a player's account:

:::code-group
```ts [Node]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const transactionintents = await openfort.transactionIntents.create({
  account: 'dac_...', // Your backend wallet ID
  chainId: 80002,
  policy: 'pol_...', // Policy for gas sponsorship
  optimistic: true,
  interactions: {
    contract: 'con_....',
    functionName: 'mint',
    functionArgs: ['pla_...'] // Player ID receiving the NFT
  }
})
```

```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d 'account=dac_...' \
  -d optimistic=true \
  -d 'interactions[0][contract]=con_....' \
  -d 'interactions[0][functionName]=mint' \
  -d 'interactions[0][functionArgs][0]=pla_...'
```
:::

#### Transferring Assets

Here's how to transfer assets from your backend wallet to another account:

:::code-group
```ts [Node]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const transactionintents = await openfort.transactionIntents.create({
  account: 'dac_...', // Your backend wallet ID
  chainId: 80002,
  policy: 'pol_...', // Policy for gas sponsorship
  optimistic: true,
  interactions: {
    contract: 'con_....',
    functionName: 'transfer',
    functionArgs: ['pla_...', '1000000000000000000'] // Player ID and amount (1 token)
  }
})
```

```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d 'account=dac_...' \
  -d optimistic=true \
  -d 'interactions[0][contract]=con_....' \
  -d 'interactions[0][functionName]=transfer' \
  -d 'interactions[0][functionArgs][0]=pla_...' \
  -d 'interactions[0][functionArgs][1]=1000000000000000000'
```
:::

#### Implementing Escrow System

This example shows how to implement an escrow system using a backend wallet:

1. First, check the player's NFT inventory:

:::code-group
```ts [Node]
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const inventory = await openfort.inventories.getPlayerNftInventory({
  player: 'pla_...',
  contract: 'con_...',
})
```

```bash [curl]
curl https://api.openfort.io/v1/accounts/acc_.../inventory/nft \
  -u "$YOUR_SECRET_KEY:" \
  -d 'contract=con_...'
```
:::

2. Then, transfer the asset to the escrow wallet:

:::code-group
```ts [Node]
const transactionintents = await openfort.transactionIntents.create({
  chainId: 80002,
  optimistic: false,
  player: 'pla_...', // Player ID
  policy: 'pol_...', // Policy for gas sponsorship
  interactions: {
    contract: 'con_...',
    functionName: "transferFrom",
    functionArgs: ['pla_...', 'dac_...', '10'], // From player to escrow wallet, token ID 10
  }
});
```

```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d optimistic=false \
  -d 'player=pla_...' \
  -d 'policy=pol_...' \
  -d 'interactions[0][contract]=con_...' \
  -d 'interactions[0][functionName]=transferFrom' \
  -d 'interactions[0][functionArgs][0]=pla_...' \
  -d 'interactions[0][functionArgs][1]=dac_...' \
  -d 'interactions[0][functionArgs][2]=10'
```
:::

:::info
To keep your application in sync with blockchain events, Openfort provides [webhooks](/docs/configuration/webhooks) for various events including transaction status changes and asset transfers.
:::


## Branding - Wallet SDK

<div align="center">
  <img alt="ecosystem-rainbow-kit" src="https://blog-cms.openfort.io/uploads/rainbow_kit_ecosystem_cf5574e8a2.png" width="80%" height="80%" />
</div>

When instantiating the **Client SDK**, you can pass in the `appearance` object to customize the appearance of the wallet. For wallet discovery, it will use [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) to embedded your branding.
The `appearance` object has the following properties:

* **icon**: a data url schema, compliant with [RFC-2397](https://www.rfc-editor.org/rfc/rfc2397).
* **logo**: a [URI](https://www.rfc-editor.org/rfc/rfc3986) pointing to an image. The image SHOULD be a square with 96x96px minimum resolution.
* **name**: a human-readable local alias of the Wallet Provider to be displayed to the user on the DApp. (e.g. `Example Wallet Extension` or `Awesome Example Wallet`)
* **reverseDomainNameSystem**: the Wallet MUST supply the `rdns` property which is intended to be a domain name from the Domain Name System in reverse syntax ordering such as `com.example.subdomain`. It’s up to the Wallet to determine the domain name they wish to use, but it’s generally expected the identifier will remain the same throughout the development of the Wallet. It’s also worth noting that similar to a user agent string in browsers, there are times where the supplied value could be unknown, invalid, incorrect, or attempt to imitate a different Wallet. Therefore, the DApp SHOULD be able to handle these failure cases with minimal degradation to the functionality of the DApp.

:::note
Getting the ecosystem id - When creating your wallet UI you need to add the ecosystem ID. It can be found in your dashboard at the settings section.
:::

Therefore, when creating your wallet SDK, you can pass in the `appearance` object to customize the appearance of the wallet.

```ts index.ts
// Set your ecosystem id. Remember to switch to your live secret key in production.
// See your ecosystem id here: https://dashboard.openfort.io/settings/project/overview
import { AppMetadata, Client } from '@openfort/ecosystem-js/client'
class EcosystemWallet extends Client {
    constructor(appMetadata?: AppMetadata) {
        super({
            // Optional App Info
            appMetadata: appMetadata,
            baseConfig: {
                // URL where the UI wallet is hosted
                ecosystemWalletDomain: 'https://wallet.ecosystem.com',
                windowStrategy: 'iframe', // or 'popup'. Rendering strategy the wallet UI.
            },
            appearance: {
              icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAFwF52RAAAACXBIWXMAAAsTAAALEwEAmpwYAAABpElEQVQ4jZ2Sv0vDUBTFf4f9Cg',
              logo: 'https://www.example.com/logo.png',
              name: 'Global Wallet',
              reverseDomainNameSystem: 'com.example.ecosystem.wallet'
            }
        });

        // Use a Proxy to allow for new method additions
        return new Proxy(this, {
            get: (target, prop) => {
                if (prop in target) {
                    const value = target[prop as keyof EcosystemWallet];
                    return typeof value === 'function' ? value.bind(target) : value;
                }
                return undefined;
            }
        });
    }
    setPolicy(options?: { policy?: string; }): void {
        return super.setPolicy(options);
    }
  }

export default EcosystemWallet;
```

You can check all the available components in the [Client SDK reference](#TODO).


## Ecosystem dashboard configuration

:::note
Creating your own global wallet is an **enterprise feature**. To enable it, please [contact us](https://t.me/joalavedra)
:::

Use the **customization** page of the dashboard to configure your ecosystem's brand settings, including name, logo, accent color, and legal policies.

<div align="center">
  <img alt="whitelabel_dashboard" src="https://blog-cms.openfort.io/uploads/whitelabel_dashboard_ef523dc779.png" width="100%" height="100%" />
</div>

### Customization options

| Customization | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| Domain        | Choose where to host your dashboard                               |
| Name          | Ecosystem name as you'd like to present it to users               |
| Logo          | Ecosystem logo                                                    |
| Brand color   | Accent color for your ecosystem                                   |
| Legal         | Used to set your own terms & conditions, and your privacy policy. |
| SDK links     | Client SDKs                                                       |
| Example links | Template examples using the ecosystem SDKs                        |


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Quickstart your global wallet \[Build and launch your custom global wallet]

:::tip
If you're looking to use an existing global wallet SDK, please refer to [use a global wallet](/docs/products/cross-app-wallet/usage/web-app-wagmi).
:::

The [**Ecosystem SDK**](https://www.npmjs.com/package/@openfort/ecosystem-js) is the easiest way to create your global wallet. It comes with a [code-splitting environment](https://developer.mozilla.org/en-US/docs/Glossary/Code_splitting), all the necessary tools to make **your wallet SDK** a reality. It is the easier way to create your own global wallet.

The Ecosystem SDK has **two main parts**:

1. `@openfort/ecosystem-js/client`: The **Client SDK** that you will use to create your wallet SDK.
2. `@openfort/ecosystem-js/core`: The **Core SDK** that you will use to create your wallet UI. Fort also includes a React specific package `@openfort/ecosystem-js/react` that you can use to get started faster.

When you finish this quickstart, this is what you will have:

<VideoSnippet title="Video" src="ZkknZ2n8Cbw" />

### Requirements

Your project will need some specific configuration to enable code splitting:

* [Typescript version 5.0.2](https://github.com/microsoft/TypeScript/releases/tag/v5.0.2) or higher.
* TS Config needs to have `compilerOptions.moduleResolution` set to `bundler`.
* Your code editor and project should have the same version of Typescript.

We'll be needed 2 main projects to create your **Ecosystem SDK**:

* **Wallet SDK**: This is the SDK that developers will use to integrate your wallet into their applications.
* **Wallet UI**: This is the UI that users will interact with when using your wallet.

::::steps
### 1. Install the ecosystem SDK

Under your **`wallet SDK folder`**, install the latest version of [Ecosystem SDK](https://www.npmjs.com/package/@openfort/ecosystem-js) using your package manager of choice:

:::info
You will need to install `@openfort/ecosystem-js` at both your wallet SDK and wallet UI projects.
:::

:::code-group
```sh [npm]
npm install @openfort/ecosystem-js
```

```sh [yarn]
yarn add @openfort/ecosystem-js
```

```sh [pnpm]
pnpm install @openfort/ecosystem-js
```
:::

### 2. Creating your wallet SDK

This is how developers will make your wallet available in their application.

<div align="center">
  <img alt="fort-architecture-1" src="https://blog-cms.openfort.io/uploads/fort_framework_step_1_a97cc606f2.svg" width="80%" height="80%" />
</div>

The easiest way to get started is to create a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object in order to map the already provided functionality of the **Client SDK**. You can nevertheless change or add new methods to fit your needs.

:::code-group
```tsx [main.ts]
import { AppMetadata, Client } from "@openfort/ecosystem-js/client";

class EcosystemWallet extends Client {
    // optional constructor arguments developers can pass to the wallet for UI customization (e.g. logo, name, etc.) https://openfort.io/reference/ecosystem-js/interfaces/client.AppMetadata.html
    constructor(appMetadata?: AppMetadata) {
        super({
            baseConfig: {
                // URL where the wallet UI is hosted:
                ecosystemWalletDomain: 'https://id.sample.openfort.io',
                windowStrategy: 'iframe', // or 'popup'. Rendering strategy the wallet UI.
            },
            appMetadata,
            // Optional App Info
            appearance: {
                icon: 'data:image/....', // a data url schema, compliant with RFC-2397.
                logo: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV', // a URI pointing to an image. The image SHOULD be a square with 96x96px minimum resolution.
                name: 'Ecosystem Wallet Name', // human-readable local alias of the Wallet Provider
                reverseDomainNameSystem: 'com.openfort.ecosystem.wallet', // domain name from the Domain Name System in reverse syntax
            }
        });

        return new Proxy(this, {
            get: (target, prop) => {
                if (prop in target) {
                    const value = target[prop as keyof EcosystemWallet];
                    return typeof value === 'function' ? value.bind(target) : value;
                }
                return undefined;
            }
        });
    }
}

export default EcosystemWallet;
```

```json [package.json]
{
  "name": "@ecosystem/wallet",
  "version": "0.0.1",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "prepublishOnly": "npm run build"
  },
  "keywords": [],
  "author": "Openfort (https://www.openfort.io)",
  "devDependencies": {
    "@types/node": "^20.4.5",
    "tsup": "^7.1.0",
    "typescript": "^5.6.2"
  },
  "dependencies": {
    "@openfort/ecosystem-js": "0.1.8"
  },
  "files": [
    "dist"
  ]
}
```

```json [tsconfig.json]
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
```
:::

You're all set! By running the `build` script you'll get a `dist` folder with the compiled code. You can now publish your package to [npm](https://www.npmjs.com/) and share it with the world.

You can check all the available client methods in the [Client SDK reference](#TODO).

#### [Wallet SDK Sample](https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-sdk)

Complete sample including auth, transactions and session keys.

### 3. Choose your signer and account system

The Ecosystem SDK is agnostic to the key management solution you choose to use. Openfort also offers an embedded wallet solution that you can use to create non-custodial wallets, referred to as `OpenfortProvider` in the Ecosystem SDK. To learn more about the available signer solutions, check out the [choose your signer](/docs/products/cross-app-wallet/setup/signers) guide.

In this guide, we'll be using the `OpenfortProvider` as the key management and account system. You can use any other wallet SDK you prefer.

#### 3.1. Setting up Openfort signer

Navigate to the **auth providers** page on the [Openfort dashboard](https://dashboard.openfort.io) by selecting your project and then clicking Auth providers Methods in the side bar in the [players page](https://dashboard.openfort.io/players). Select the account types you'd like users to be able to login with. For more information on how to enable social logins, check out the [dashboard docs](/docs/configuration/social-login).

From the [Openfort Dashboard](https://dashboard.openfort.io) for select your desired app, navigate to the [developers page](https://dashboard.openfort.io/developers/configuration/api-keys) in the top bar. On the de tab, find the API keys section. Get your Openfort API keys, you will need it in the next step.

You will find two keys:

* **Publishable Key**: This value can be safely exposed in a client-side environment.
* **Secret Key**: This value should never be exposed in a client-side environment. It should be kept secure and used only in a server-side environment. Learn more on how to use it in the [server-side guide](/docs/products/server/wallet). You can [further secure it](/docs/configuration/api-keys) for production applications.

To generate non custodial wallets, you will need to create a Shield instance. At the [API keys page](https://dashboard.openfort.io/developers/configuration/api-keys), scroll down to the Shield section and click on the **Create Shield keys** button.
A **one time pop-up** will appear with a variable called **encryption share**. Its very important that you store it safely. You will not be able to see it again.

Then, in your page, you will see two Shield keys:

* **Publishable Key**: This value can be safely exposed in a client-side environment.
* **Secret Key**: This value should never be exposed in a client-side environment.

### 4. Creating your wallet UI

The **wallet UI** is how information is shown to wallet users. Under your **`wallet UI folder`**, install the latest version of [Ecosystem SDK](https://www.npmjs.com/package/@openfort/ecosystem-js) using your package manager of choice. Remember to comply with the requirements to benefit from code splitting.

:::info
To make things more concrete, we'll be using `OpenfortProvider` as the key management and account system. You can use any other wallet SDK you prefer.
:::

<div align="center">
  <img alt="fort-architecture-2" src="https://blog-cms.openfort.io/uploads/fort_framework_step_2_5ff477cb98.svg" width="80%" height="80%" />
</div>

`@openfort/ecosystem-js` SDK comes with a set of pre-built **React** components that you can use to create your wallet UI. To learn how to customize it further, head to the [UI screens guide](/docs/products/cross-app-wallet/setup/react/wallet-ui).

In your project, import the **EcosystemProvider** component and wrap your app with it. Concretely, the `EcosystemProvider` must wrap any component or page that will use the Ecosystem SDK in your react app. It is generally recommended to render it as close to the root of your application as possible.

For example, in a [NextJS](https://nextjs.org/) or [Create React App](https://create-react-app.dev/) project, you may wrap your components like so:

#### Install the required dependencies

:::code-group
```sh [npm]
npm install @openfort/ecosystem-js wagmi viem@2.x @tanstack/react-query
```

```sh [yarn]
yarn add @openfort/ecosystem-js wagmi viem@2.x @tanstack/react-query
```
:::

* TypeScript is optional, but highly recommended.

#### Implementation

:::info
Getting the ecosystem id: When creating your **wallet UI** you need to add the *ecosystem ID*. It can be found in your dashboard at the [settings section](https://dashboard.openfort.io/settings/project/overview).
:::

##### Create React App

:::code-group
```tsx [main.tsx]
// Set your publishable key, shield publishable key and ecosystem id. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
// See your ecosystem ID here: https://dashboard.openfort.io/settings/project/overview
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { BrowserRouter, useNavigate } from 'react-router-dom';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider } from '@tanstack/react-query';

import * as Wagmi from './lib/Wagmi';
import * as Query from './lib/Query'
import { EcosystemProvider, OpenfortProvider, RecoveryMethod } from '@openfort/ecosystem-js/react';

async function getShieldSession(accessToken:string):Promise<string> {
  // When using AUTOMATIC embedded wallet recovery, an encryption session is required.
  // Sample encryption session generation backend: https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-ui/backend
  const response = await fetch(`${process.env.REACT_APP_BACKEND_URL}/api/protected-create-encryption-session`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch shield session');
  }

  const data = await response.json();
  return data.session;
}

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

export default function Providers({children}: {children: React.ReactNode}) {
const nav = useNavigate()
return (
  <EcosystemProvider
    appName='Rapidfire ID'
    navigateTo={(appState) => {
      nav({
        pathname: appState?.to,
        search: appState?.search
      })
    }}
    theme='midnight'
    logoUrl='https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV'
  >
    <WagmiProvider config={Wagmi.config}>
      <QueryClientProvider
        client={Query.client}
      >
        <OpenfortProvider
          // If you're using third party authentication with Openfort (i.e. your own auth or providers like Firebase), set thirdPartyAuthentication to true.
          thirdPartyAuthentication={false}
          ecosystemId={process.env.REACT_APP_OPENFORT_ECOSYSTEM_ID}
          onRedirectCallback={(appState) => {
            return nav(appState?.returnTo || window.location.pathname);
          }}
          overrides={{}}  
          publishableKey={process.env.REACT_APP_OPENFORT_PUBLIC_KEY}
          // To choose your recovery method, set the recoveryMethod to either 'AUTOMATIC' or 'PASSWORD'
          // Learn more about configure embedded signers: https://openfort.io/docs/products/embedded-wallet/react/kit/wallets/
          embeddedSignerConfiguration={
            {
              shieldPublishableKey: process.env.REACT_APP_SHIELD_PUBLIC_KEY,
              recoveryMethod: RecoveryMethod.AUTOMATIC,
              // If you're using AUTOMATIC recovery, you need to provide an encryption session. 
              // If you're only using PASSWORD recovery, you can remove this function.
              getEncryptionSessionFn(getAccessToken) {
                return getShieldSession(getAccessToken);
              }
            }
          }
        >
          {children}
        </OpenfortProvider>
      </QueryClientProvider>
    </WagmiProvider>
  </EcosystemProvider>
);
}

```

```tsx [App.tsx]
import { 
  WalletGrantPermissions,
  WalletSendCalls, 
  EthRequestAccounts, 
  EthSendTransaction, 
  EthSignTypedDataV4, 
  PersonalSign, 
  WalletShowCalls,
  withAuthenticationRequired,
  Settings,
  UnsupportedMethod,
  LoginMethods,
  Recover
} from '@openfort/ecosystem-js/react';
import { Route, Routes } from 'react-router-dom';
import Loading from './Loading';


const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

function App() {
  return (
    <Routes>
      {/* Required endpoints for EIP-1193 methods */}
      <Route path='/sign/personal-sign' element={<ProtectedRoute component={PersonalSign} />} />
      <Route path='/sign/eth-sign-typed-data-v-4' element={<ProtectedRoute component={EthSignTypedDataV4} />} />
      <Route path='/sign/eth-send-transaction' element={<ProtectedRoute component={EthSendTransaction} />} />
      <Route path='/sign/wallet-grant-permissions' element={<ProtectedRoute component={WalletGrantPermissions} />} />
      <Route path='/sign/wallet-show-calls' element={<ProtectedRoute component={WalletShowCalls} />} />
      <Route path='/sign/wallet-send-calls' element={<ProtectedRoute component={WalletSendCalls} />} />
      <Route path='/sign/eth-request-accounts' element={<ProtectedRoute component={EthRequestAccounts} />} />
      <Route path='/settings' element={<ProtectedRoute component={Settings} />} />
      <Route path='/sign' element={<ProtectedRoute component={Loading} />} />
      <Route path='*' element={<UnsupportedMethod />} />
      
      {/* OpenfortProvider specific methods for EmbeddedSigner recovery (password based) and authentication */}
      <Route path='/authenticate' element={<LoginMethods />} />
      <Route path='/recover' element={<Recover />} />
    </Routes>
  );
}

export default App;
```

```tsx [Loading.tsx]
import { Layout } from '@openfort/ecosystem-js/react';
import React from 'react';

const Loading: React.FC = () => {
  return (
    // Not how its wrapped in the Layout component, to ensure the styles are applied
    <Layout>
      <svg
        width="20"
        height="20"
        viewBox="0 0 20 20"
        className="animate-spin"
      >
        <circle 
          cx="25" 
          cy="25" 
          r="20" 
          fill="none" 
          stroke="#ffffff" 
          strokeWidth="5"
          strokeLinecap="round"
          strokeDasharray="80"
          strokeDashoffset="60"
        />
      </svg>
      
      {/* Adding custom styles */}
      <style
        dangerouslySetInnerHTML={{
          __html: `
            .animate-spin {
              animation: spin 1s linear infinite;
            }
            
            @keyframes spin {
              from {
                transform: rotate(0deg);
              }
              to {
                transform: rotate(360deg);
              }
            }
          `
        }}
      />
    </Layout>
  );
};

export default Loading;
```

```ts [lib/Wagmi.ts]
// Configure your wagmi instance with the chains you want to support: https://wagmi.sh/react/guides/chain-properties
import { http, createConfig } from 'wagmi'
import { baseSepolia, polygonAmoy, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [polygonAmoy, baseSepolia, sepolia],
  transports: {
    [polygonAmoy.id]: http(),
    [baseSepolia.id]: http(),
    [sepolia.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}
```

```ts [lib/Query.ts]
import { QueryClient } from '@tanstack/react-query'

export const client = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
      retry: 0,
    },
  },
})
```
:::

**Components:**

* Check all the available `OpenfortProvider` configuration methods at [OpenfortProvider SDK reference](#TODO).
* Check all the available `EcosystemProvider` configuration methods at [EcosystemProvider SDK reference](#TODO).

#### Configure Supported Chains

As you can see above, its required that you configure [Wagmi](https://wagmi.sh) and the chains you plan on enabling for your wallet.

Note that, to enable transaction simulation through asset changes, the **Ecosystem SDK** internally requires the [`eth_simulateV1`](https://github.com/ethereum/execution-apis/pull/484) [JSON-RPC method](https://github.com/ethereum/execution-apis/pull/484), so you will need to provide an RPC endpoint that supports this method (or disable simulation through the EcosystemProvider using `disableTransactionSimulation`).

#### [Wallet UI Sample](https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-ui/frontend)

Sample wallet UI with all the necessary screens.
::::


## Design and customize your wallet

Openfort **global wallets** come with a default set of screens for authentication, session key confirmation, sign typed message, configuration, and transaction confirmation. These screens are designed to be customizable to fit your brand and user experience. Openfort provides helpers to the most popular frameworks to make it easier to integrate the global wallets.

<div align="center">
  <img alt="ecosystem-architecture" src="https://blog-cms.openfort.io/uploads/Whitelabel_wallet_design_6df94dcb9b.png" width="80%" height="80%" />
</div>

### Wallet Routes

Whenever the users of a wallet make a request, this request is eventually received by the **Wallet UI** which is in charge of directing the user to the correct screen.

The **Wallet UI** expects the following routes to exist in your project:

| Route                          | Description              |
| ------------------------------ | ------------------------ |
| /sign/personal-sign            | personal\_sign           |
| /sign/eth-sign-typed-data-v-4  | eth\_signTypedData\_v4   |
| /sign/eth-send-transaction     | eth\_signTransaction     |
| /sign/eth-request-accounts     | eth\_requestAccounts     |
| /sign/wallet-show-calls        | wallet\_showCallsStatus  |
| /sign/wallet-send-calls        | wallet\_sendCalls        |
| /sign/wallet-grant-permissions | wallet\_grantPermissions |
| /sign                          | Loading screen           |

### Wallet Window Strategy

The `Ecosystem SDK` supports two window modes, `popup` and `iframe`, which can be configured through the prop `windowStrategy` when creating the wallet SDK with `@openfort/ecosystem-js/client`.

#### iframe

The wallet is embedded in the page. In mobile no new tab is required to show the wallet action.

| DESKTOP                                                                                                                                                                                                                           | MOBILE                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <div align="center"><video width="100%" controls muted playsInline><source src="https://blog-cms.openfort.io/uploads/rapidfire_demo_bae171c041.mp4" type="video/mp4" />Your browser does not support the video tag.</video></div> | <div align="center"><video width="100%" controls muted playsInline><source src="https://blog-cms.openfort.io/uploads/rapidfire_ios_iframe_demo_7c8c888966.mp4" type="video/mp4" />Your browser does not support the video tag.</video></div> |

#### Popup

The wallet is opened in a new window both in mobile and desktop.

| DESKTOP                                                                                                                                                                                                                                         | MOBILE                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <div align="center"><video width="100%" controls muted playsInline><source src="https://blog-cms.openfort.io/uploads/rapidfire_desktop_popup_demo_ca4c20f2da.mp4" type="video/mp4" />Your browser does not support the video tag.</video></div> | <div align="center"><video width="100%" controls muted playsInline><source src="https://blog-cms.openfort.io/uploads/rapidfire_ios_popup_demo_fb01ebd826.mp4" type="video/mp4" />Your browser does not support the video tag.</video></div> |

Here's how the **windowStrategy** is set in the `Rapidfire ID` sample wallet:

```tsx index.tsx
import { AppMetadata, Client, ThirdPartyAuthProvider } from "@openfort/ecosystem-js/client";

class EcosystemWallet extends Client {
    constructor(appMetadata?: AppMetadata) {
        super({
            baseConfig: {
                ecosystemWalletDomain: 'https://id.sample.openfort.io',
                windowStrategy: 'iframe',
            },
            appMetadata,
            appearance: {
                icon: 'data:image/...',
                logo: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV',
                name: 'Rapidfire ID',
                reverseDomainNameSystem: 'com.rapidfire.id'
            }
        });

        // Use a Proxy to allow for new method additions
        return new Proxy(this, {
            get: (target, prop) => {
                if (prop in target) {
                    const value = target[prop as keyof EcosystemWallet];
                    return typeof value === 'function' ? value.bind(target) : value;
                }
                return undefined;
            }
        });
    }

    authenticate(token: string) {
        return super.authenticateWithThirdPartyProvider({ token: token, provider: ThirdPartyAuthProvider.FIREBASE });
    }

    // Add new methods here
    setPolicy(options?: { policy?: string; }): void {
        return super.setPolicy(options);
    }

}

export default EcosystemWallet;
```

#### [Setting Client SDK](https://github.com/openfort-xyz/ecosystem-sample/blob/main/wallet-sdk/src/index.ts#L9)

Complete sample setting the `windowStrategy` in the client SDK.

### Wallet UI Customization

The `Ecosystem SDK` uses ConnectKit themes, and offers the same theming and customization options. You can edit fonts, colors, and other styling via the **theme** and **customTheme** props of `EcosystemProvider`. For more detail on themes, see the [ConnectKit docs](https://docs.family.co/connectkit/customization).


## Ecosystem wallet signers

The Ecosystem SDK is agnostic to the key management solution you choose to use.

#### [Openfort Social Login Signer](/docs/products/cross-app-wallet/setup/signers/openfort)

Non-custodial signer generated using MPC-SSS with social login compatibility.

#### [Passkey Signer](/docs/products/cross-app-wallet/setup/signers/passkey)

Self-custodial signer controlled by onchain Passkey (WebAuthN) validation.


## Using Openfort signer

:::info
If you want to check out a live sample app using Openfort signers, check out the [live demo with RapidFire](https://rapidfire.sample.openfort.io/).
:::

### Configure Authentication Methods

Navigate to the **auth providers** page on the [Openfort dashboard](https://dashboard.openfort.io) by selecting your project and then clicking **Auth providers Methods** in the side bar in the [players page](https://dashboard.openfort.io/players). Select the account types you'd like users to be able to login with. For more information on how to enable social logins, check out the [dashboard docs](/docs/configuration/social-login).

:::note
As soon as you enable each provider from your dashboard, it will automatically appear as an option in the authentication page.
:::

From the [Openfort Dashboard](https://dashboard.openfort.io) for select your desired app, navigate to the [developers page](https://dashboard.openfort.io/developers/configuration/api-keys) in the top bar. On the de tab, find the API keys section. Get your Openfort API keys, you will need it in the next step.

You will find two keys:

* **Publishable Key**: This value can be safely exposed in a client-side environment.
* **Secret Key**: This value should never be exposed in a client-side environment. It should be kept secure and used only in a server-side environment. Learn more on how to use it in the [server-side guide](/docs/products/server). You can [further secure it](/docs/configuration/api-keys) for production applications.

To generate non custodial wallets, you will need to create a Shield instance. At the [API keys page](https://dashboard.openfort.io/developers/configuration/api-keys), scroll down to the Shield section and click on the **Create Shield keys** button.
A **one time pop-up** will appear with a variable called **encryption share**. Its very important that you store it safely. You will not be able to see it again.

Then, in your page, you will see two Shield keys:

* **Publishable Key**: This value can be safely exposed in a client-side environment.
* **Secret Key**: This value should never be exposed in a **client**-side environment.

### Creating your wallet UI

The **wallet UI** is how information is shown to wallet users. Under your **`wallet UI` folder**, install the latest version of [Ecosystem SDK](https://www.npmjs.com/package/@openfort/ecosystem-js) using your package manager of choice. Remember to comply with the requirements to benefit from code splitting.

<div>
  **Getting the ecosystem id**: When creating your **wallet UI** you need to add the *ecosystem ID*. It can be found in your dashboard in the [settings section](https://dashboard.openfort.io/settings/project/overview).
</div>

##### Create React App

:::code-group
```tsx [index.tsx]
// Set your publishable key, shield publishable key and ecosystem id. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
// See your ecosystem ID here: https://dashboard.openfort.io/settings/project/overview
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { BrowserRouter, useNavigate } from 'react-router-dom';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider } from '@tanstack/react-query';

import * as Wagmi from './lib/Wagmi';
import * as Query from './lib/Query'
import { EcosystemProvider, OpenfortProvider, RecoveryMethod } from '@openfort/ecosystem-js/react';

async function getShieldSession(accessToken:string):Promise<string> {
  // When using AUTOMATIC embedded wallet recovery, an encryption session is required.
  // Sample encryption session generation backend: https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-ui/backend
  const response = await fetch(`${process.env.REACT_APP_BACKEND_URL}/api/protected-create-encryption-session`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch shield session');
  }

  const data = await response.json();
  return data.session;
}

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

export default function Providers({children}: {children: React.ReactNode}) {
const nav = useNavigate()
return (
  <EcosystemProvider
    appName='Rapidfire ID'
    navigateTo={(appState) => {
      nav({
        pathname: appState?.to,
        search: appState?.search
      })
    }}
    theme='midnight'
    logoUrl='https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV'
  >
    <WagmiProvider config={Wagmi.config}>
      <QueryClientProvider
        client={Query.client}
      >
        <OpenfortProvider
          // If you're using third party authentication with Openfort (i.e. your own auth or providers like Firebase), set thirdPartyAuthentication to true.
          thirdPartyAuthentication={false}
          ecosystemId={process.env.REACT_APP_OPENFORT_ECOSYSTEM_ID}
          onRedirectCallback={(appState) => {
            return nav(appState?.returnTo || window.location.pathname);
          }}
          overrides={{}}      
          publishableKey={process.env.REACT_APP_OPENFORT_PUBLIC_KEY}
          // To choose your recovery method, set the recoveryMethod to either 'AUTOMATIC' or 'PASSWORD'
          // Learn more about configure embedded signers: https://openfort.io/docs/products/embedded-wallet/react/kit/wallets/
          embeddedSignerConfiguration={
            {
              shieldPublishableKey: process.env.REACT_APP_SHIELD_PUBLIC_KEY,
              recoveryMethod: RecoveryMethod.AUTOMATIC,
              // If you're using AUTOMATIC recovery, you need to provide an encryption session. 
              // If you're only using PASSWORD recovery, you can remove this function.
              getEncryptionSessionFn(getAccessToken) {
                return getShieldSession(getAccessToken);
              }
            }
          }
        >
          {children}
        </OpenfortProvider>
      </QueryClientProvider>
    </WagmiProvider>
  </EcosystemProvider>
);
}
```

```tsx [App.tsx]
import { 
  WalletGrantPermissions,
  WalletSendCalls, 
  EthRequestAccounts, 
  EthSendTransaction, 
  EthSignTypedDataV4, 
  PersonalSign, 
  WalletShowCalls,
  withAuthenticationRequired,
  Settings,
  UnsupportedMethod,
  LoginMethods,
  Recover
} from '@openfort/ecosystem-js/react';
import { Route, Routes } from 'react-router-dom';
import Loading from './Loading';


const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

function App() {
  return (
    <Routes>
      {/* Required endpoints for EIP-1193 methods */}
      <Route path='/sign/personal-sign' element={<ProtectedRoute component={PersonalSign} />} />
      <Route path='/sign/eth-sign-typed-data-v-4' element={<ProtectedRoute component={EthSignTypedDataV4} />} />
      <Route path='/sign/eth-send-transaction' element={<ProtectedRoute component={EthSendTransaction} />} />
      <Route path='/sign/wallet-grant-permissions' element={<ProtectedRoute component={WalletGrantPermissions} />} />
      <Route path='/sign/wallet-show-calls' element={<ProtectedRoute component={WalletShowCalls} />} />
      <Route path='/sign/wallet-send-calls' element={<ProtectedRoute component={WalletSendCalls} />} />
      <Route path='/sign/eth-request-accounts' element={<ProtectedRoute component={EthRequestAccounts} />} />
      <Route path='/sign/settings' element={<ProtectedRoute component={Settings} />} />
      <Route path='/sign/' element={<ProtectedRoute component={Loading} />} />
      <Route path='*' element={<UnsupportedMethod />} />
      
      {/* OpenfortProvider specific methods for EmbeddedSigner recovery (password based) and authentication */}
      <Route path='/sign/authenticate' element={<LoginMethods />} />
      <Route path='/sign/recover' element={<Recover />} />
    </Routes>
  );
}

export default App;
```

```tsx [Loading.tsx]
import { Layout } from '@openfort/ecosystem-js/react';
import React from 'react';

const Loading: React.FC = () => {
  return (
    // Not how its wrapped in the Layout component, to ensure the styles are applied
    <Layout>
      <svg
        width="20"
        height="20"
        viewBox="0 0 20 20"
        className="animate-spin"
      >
        <circle 
          cx="25" 
          cy="25" 
          r="20" 
          fill="none" 
          stroke="#ffffff" 
          strokeWidth="5"
          strokeLinecap="round"
          strokeDasharray="80"
          strokeDashoffset="60"
        />
      </svg>
      
      {/* Adding custom styles */}
      <style
        dangerouslySetInnerHTML={{
          __html: `
            .animate-spin {
              animation: spin 1s linear infinite;
            }
            
            @keyframes spin {
              from {
                transform: rotate(0deg);
              }
              to {
                transform: rotate(360deg);
              }
            }
          `
        }}
      />
    </Layout>
  );
};

export default Loading;
```

```ts [lib/Wagmi.ts]
// Configure your wagmi instance with the chains you want to support: https://wagmi.sh/react/guides/chain-properties
import { http, createConfig } from 'wagmi'
import { baseSepolia, polygonAmoy } from 'wagmi/chains'

export const config = createConfig({
  chains: [polygonAmoy, baseSepolia],
  transports: {
    [polygonAmoy.id]: http(),
    [baseSepolia.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}
```

```ts [lib/Query.ts]
import { QueryClient } from '@tanstack/react-query'

export const client = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
      retry: 0,
    },
  },
})
```
:::

**Components:**

* Check all the available `OpenfortProvider` configuration methods at [OpenfortProvider SDK reference](#TODO).
* Check all the available `EcosystemProvider` configuration methods at [EcosystemProvider SDK reference](#TODO).

#### Configure Supported Chains

As you can see above, its required that you configure [Wagmi](https://wagmi.sh) and the chains you plan on enabling for your wallet.

Note that, to enable transaction simulation through asset changes, the **Ecosystem SDK** internally requires the [`eth_simulateV1`](https://github.com/ethereum/execution-apis/pull/484) [JSON-RPC method](https://github.com/ethereum/execution-apis/pull/484), so you will need to provide an RPC endpoint that supports this method (or disable simulation through the EcosystemProvider using `disableTransactionSimulation`).

### Sample Openfort authentication

#### [Wallet UI Sample](https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-ui/frontend)

Sample wallet UI with all the necessary screens.

### Using a custom auth provider

Openfort's global wallets are fully-compatible with any authentication provider that supports JWT-based, stateless authentication.

* Use a custom authentication provider (easy to integrate alongside your existing stack).

### Sample third-party authentication

#### [Wallet SDK Sample](https://github.com/openfort-xyz/ecosystem-sample/tree/feat/third-party-auth)

Complete sample using Firebase as an authentication provider for the global wallet.


## Passkey (Webauthn) signer

:::info
If you want to check out a live sample app using Passkey signers, check out the [live demo with RapidSafe](https://rapidsafe.sample.openfort.io/).
:::

#### Install the required dependencies

In this sample, we'll be using the [Safe smart account](https://safe.global), with [Safe7579 adapter](https://github.com/rhinestonewtf/safe7579) to add support for **Passkeys** and **session keys**.

:::code-group
```sh [npm]
npm install @openfort/ecosystem-js permissionless wagmi viem@2.x @tanstack/react-query
```

```sh [yarn]
yarn add @openfort/ecosystem-js permissionless wagmi viem@2.x @tanstack/react-query
```

```sh [pnpm]
pnpm add @openfort/ecosystem-js permissionless wagmi viem@2.x @tanstack/react-query
```
:::

* TypeScript is optional, but highly recommended.

#### Implementation

:::info
Please refer to the complete code for the [Wallet UI](https://github.com/openfort-xyz/ecosystem-sample-safe-passkeys/tree/main/wallet-ui/frontend) if you want to see the full implementation of the Passkey signer.
:::

##### Create React App

:::code-group
```tsx [index.tsx]
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { BrowserRouter, useNavigate } from 'react-router-dom';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider } from '@tanstack/react-query';

import * as Wagmi from './lib/Wagmi';
import * as Query from './lib/Query'
import { EcosystemProvider } from '@openfort/ecosystem-js/react';

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

export default function Providers({children}: {children: React.ReactNode}) {
const nav = useNavigate()
return (
  <EcosystemProvider
    appName='RapidSafe'
    navigateTo={(appState) => {
      nav({
        pathname: appState?.to,
        search: appState?.search
      })
    }}
    theme='midnight'
    logoUrl='https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV'
  >
    <WagmiProvider config={Wagmi.config}>
      <QueryClientProvider
        client={Query.client}
      >
        <RapidsafeProvider
          debugMode={true}
          onRedirectCallback={(appState) => {
            return nav(appState?.returnTo || window.location.pathname);
          }}
          >
          {children}
        </RapidsafeProvider>
      </QueryClientProvider>
    </WagmiProvider>
  </EcosystemProvider>
);
}
```

```tsx [App.tsx]
import { 
  WalletGrantPermissions,
  WalletSendCalls,
  EthSendTransaction, 
  EthSignTypedDataV4, 
  PersonalSign, 
  WalletShowCalls,
  withAuthenticationRequired,
  Settings,
  UnsupportedMethod,
  LoginMethods,
  Recover
} from '@openfort/ecosystem-js/react';
import { Route, Routes } from 'react-router-dom';
import Loading from './Loading';
import EthRequestAccounts from './routes/sign/EthRequestAccounts';

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};

function App() {
  return (
    <Routes>
      {/* Required endpoints for EIP-1193 methods */}
      <Route path='/sign/personal-sign' element={<ProtectedRoute component={PersonalSign} />} />
      <Route path='/sign/eth-sign-typed-data-v-4' element={<ProtectedRoute component={EthSignTypedDataV4} />} />
      <Route path='/sign/eth-send-transaction' element={<ProtectedRoute component={EthSendTransaction} />} />
      <Route path='/sign/wallet-grant-permissions' element={<ProtectedRoute component={WalletGrantPermissions} />} />
      <Route path='/sign/wallet-show-calls' element={<ProtectedRoute component={WalletShowCalls} />} />
      <Route path='/sign/wallet-send-calls' element={<ProtectedRoute component={WalletSendCalls} />} />
      <Route path='/sign/eth-request-accounts' element={<ProtectedRoute component={EthRequestAccounts} />} />
      <Route path='/sign/settings' element={<ProtectedRoute component={Settings} />} />
      <Route path='/sign/' element={<ProtectedRoute component={Loading} />} />
      <Route path='*' element={<UnsupportedMethod />} />
    </Routes>
  );
}

export default App;
```

```tsx [Loading.tsx]
import { Layout } from '@openfort/ecosystem-js/react';
import React from 'react';

const Loading: React.FC = () => {
  return (
    // Not how its wrapped in the Layout component, to ensure the styles are applied
    <Layout>
      <svg
        width="20"
        height="20"
        viewBox="0 0 20 20"
        className="animate-spin"
      >
        <circle 
          cx="25" 
          cy="25" 
          r="20" 
          fill="none" 
          stroke="#ffffff" 
          strokeWidth="5"
          strokeLinecap="round"
          strokeDasharray="80"
          strokeDashoffset="60"
        />
      </svg>
      
      {/* Adding custom styles */}
      <style
        dangerouslySetInnerHTML={{
          __html: `
            .animate-spin {
              animation: spin 1s linear infinite;
            }
            
            @keyframes spin {
              from {
                transform: rotate(0deg);
              }
              to {
                transform: rotate(360deg);
              }
            }
          `
        }}
      />
    </Layout>
  );
};

export default Loading;
```

```ts [lib/Wagmi.ts]
// Configure your wagmi instance with the chains you want to support: https://wagmi.sh/react/guides/chain-properties
import { rapidsafe, RapidsafeParameters } from '../providers/RapidsafeProvider/Connector';
import { http, createConfig, createStorage } from 'wagmi'
import { baseSepolia } from 'wagmi/chains'

const RapidsafeConfig: RapidsafeParameters = {
  rpId: window.location.hostname
};
export const config = createConfig({
  chains: [baseSepolia],
  connectors: [
    rapidsafe(RapidsafeConfig),
  ],
  multiInjectedProviderDiscovery: false,
  storage: createStorage({ storage: localStorage }),
  transports: {
    [baseSepolia.id]: http()
  },
})
export type Chain = (typeof config.chains)[number]
export type ChainId = Chain['id']
export const getChainConfig = (chainId: ChainId) =>
  config.chains.find((c) => c.id === chainId)

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}
```

```ts [lib/Query.ts]
import { QueryClient } from '@tanstack/react-query'

export const client = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
      retry: 0,
    },
  },
})
```
:::

**Components:**

* Check all the available `EcosystemProvider` configuration methods at [EcosystemProvider SDK reference](#TODO).

#### Configure Supported Chains

As you can see above, its required that you configure [Wagmi](https://wagmi.sh) and the chains you plan on enabling for your wallet.

Note that, to enable transaction simulation through asset changes, the **Ecosystem SDK** internally requires the [`eth_simulateV1`](https://github.com/ethereum/execution-apis/pull/484) [JSON-RPC method](https://github.com/ethereum/execution-apis/pull/484), so you will need to provide an RPC endpoint that supports this method (or disable simulation through the EcosystemProvider using `disableTransactionSimulation`).

### Sample

#### [Wallet UI with Passkeys Sample](https://github.com/openfort-xyz/ecosystem-sample-safe-passkeys/tree/main/wallet-ui/frontend)

Sample wallet UI with all the necessary screens.


## Third-party auth providers

Openfort's embedded wallets are fully-compatible with any authentication provider that supports JWT-based, stateless authentication.

:::warning
To make these instructions concrete, this guide uses [Firebase](https://firebase.com) as a sample third party auth provider.
:::

First, follow the guide on how to [configure third party authentication](/docs/configuration/external-auth).

The supported authentication providers are `ACCELBYTE`, `CUSTOM`, `FIREBASE`, `SUPABASE`, `LOOTLOCKER`, `PLAYFAB` and `OIDC`.

To authenticate with a third-party provider, use the `authenticateWithThirdPartyProvider` method. This method exchanges a token from your authentication provider for an Openfort session.

:::code-group
```tsx [auth.tsx]
import openfort from "./openfortConfig";
import { signInWithPopup, GoogleAuthProvider } from "firebase/auth";
import { auth } from "./firebaseConfig";

const provider = new GoogleAuthProvider();

async function handleGoogleLogin() {
  try {
    const result = await signInWithPopup(auth, provider);
    const idToken = await result.user.getIdToken();
    
    await openfort.auth.authenticateWithThirdPartyProvider({
      provider: 'firebase',
      token: idToken,
      tokenType: 'idToken',
    });
  } catch (error) {
    console.error('Error during authentication:', error);
  }
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

```json [response.json]
{
  "player": {
    "id": "pla_...",
    "object": "player",
    "createdAt": 1699449600,
    "linkedAccounts": [
      {
        "provider": "firebase",
        "email": "player@example.com",
        "disabled": false
      }
    ]
  }
}
```
:::


## External Wallet Login

Connect wallet via the [Sign in With Ethereum (SIWE)](https://eips.ethereum.org/EIPS/eip-4361) standard. Catered to users who prefer to authenticate using their external wallets, supporting various types such as injected, browser-based, and mobile wallets. Openfort’s integration facilitates a secure and direct authentication process using these wallets.

First create a challenge for the user to sign with their wallet by constructing a SIWE challenge using the nonce returned from the server:

:::code-group
```tsx [auth.tsx]
import openfort from "./openfortConfig"
const address = 'EXTERNAL_WALLET_ADDRESS';

async function initSIWE() {
  await openfort.auth.initSIWE({address});
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});
export default openfort;
```
:::

Then, verify the SIWE signature to authenticate the user:

* `walletClientType`: e.g. coinbaseWallet, metamask, etc.
* `connectorType`: wallet\_connect\_v2, injected, coinbase\_wallet, etc.

:::code-group
```jsx [authSIWE.jsx]
import openfort from "./openfortConfig"
const address = 'EXTERNAL_WALLET_ADDRESS';

async function authSIWE(signature, message, walletClientType, connectorType) {
  await openfort.auth.authenticateWithSIWE({
    signature: signature,
    message: SIWEMessage,
    connectorType: connector?.type,
    walletClientType: connector?.name,
  });
}
```

```json [response.json]
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "wallet",
              "address": "0x1234567890abcdef",
              "disabled": false,
          }
      ]
  },
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJhdWQiOiJwcm9fOGY3ZTM1NTktMjhkNy00MWE2LTgxNGMtMjU0OTkzZTdkNjFkLXRlc3QiLCJleHAiOjE3MTA5ODI2MDIsImlhdCI6MTcxMDk3OTAwMiwiaXNzIjoib3BlbmZvcnQueHl6Iiwic2lkIjoiMzhhMDdmMzktMTUxOS00MjE0LWJmNmMtNzI0Zjg0ZDBiZGQwIiwic3ViIjoicGxhX2NjOWVkMmI3LWM1ZjUtNGM0My04ZGNhLWM0YjEwNGJhMTc2MiJ9.EcFtS__GwyxJu1S3tO7jMBbTCIJCpqsoNxxJrqILrKjNl2N5-SIMG2z_s2Vs8ztG6KAVy6zIp6P9GzfD7s4JiA",
  "refreshToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJzaWQiOiIzOGEwN2YzOS0xNTE5LTQyMTQtYmY2Yy03MjRmODRkMGJkZDAiLCJpYXQiOjE3MTA5NzkwMDIsImV4cCI6MTcxMzU3MTAwMn0.koNd4eoevBQQR3-z0CMGL5qVzOURZEeAgjvrHMRloLgDbScS2Qbi4W-vf2fE0fYOWUIAHnAq7cDABNwSQrEvSQ"
}
```
:::

And you’re done! The user is now authenticated and can access your application.

Uppon successful authentication, the SDK will return a token that can be used to authenticate the user in your application.


## Guest Users

Guest accounts allow users to immediately start using your application without going through a full registration process. This feature is particularly useful for applications where you want to reduce friction in the user onboarding process.

#### Key Features

* They are locally persisted, so guest users can leave and return to the same account on the same device.
* Locally persisted sessions.
* Fully functional embedded wallets.
* Upgradeable to fully logged-in accounts.
* They can be logged out and deleted as needed.

{/* Note: User data and embedded wallets from guest sessions cannot be merged into an existing user account — guest accounts can only be upgraded into a new user account. If a guest user wants to log in with an existing account, you must delete the guest user session first. */}

### Implementation

#### Create a guest account (client-side)

Use the `signUpGuest` method from the Openfort SDK to create a guest account:

:::code-group
```tsx [auth.tsx]
import openfort from "./openfortConfig";

async function handleGuest() {
  try {
    const data = await openfort.auth.signUpGuest();
    // Handle successful guest registration
    // The response includes player information and authentication tokens
  } catch (error) {
    // Handle error
  }
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

```json [response.json]
{
  "player": {
    "id": "pla_...",
    "object": "player",
    "createdAt": 1234567890,
    "linkedAccounts": []
  },
  "token": "eyJhbG...",
  "refreshToken": "eyJhbG..."
}
```
:::

Upon successful registration, you'll receive a response containing the player information and authentication tokens as shown in the JSON tab above.

{/* Integration tip: Display guest access alongside normal login options. Use clear labeling to distinguish between guest and full account creation. */}

```javascript
const LoginOptions = () => {
  return (
    <div className="space-y-4">
      <Button onClick={handleGuest}>
        Continue as Guest
      </Button>
      <Button onClick={() => router.push("/login")}>
        Login or Create Account
      </Button>
    </div>
  );
};
```

#### Upgrade a guest user to a logged-in user

Simply call [link method](/docs/products/embedded-wallet/javascript/auth/user-management/linking) to enable the guest user to upgrade their account to a logged-in account using any authentication method of their choice.

### Example Implementation

Here's a complete example of a guest authentication flow:

:::code-group
```javascript [GuestAuth.jsx]
import openfort from "./openfortConfig";
import { useState } from "react";

function GuestAuth() {
  const router = useRouter();
  const [status, setStatus] = useState(null);

  const handleGuest = async () => {
    setStatus({
      type: "loading",
      title: "Creating guest account...",
    });

    try {
      const data = await openfort.auth.signUpGuest();
      
      setStatus({
        type: "success",
        title: "Guest account created",
      });
      
      // Store credentials and redirect
      openfort.auth.storeCredentials({
        player: data.player.id,
        accessToken: data.token,
        refreshToken: data.refreshToken,
      });
      
      router.push("/");
    } catch (error) {
      setStatus({
        type: "error",
        title: "Error creating guest account",
      });
    }
  };

  return (
    <div>
      <Button onClick={handleGuest}>
        {status?.type === "loading" ? (
          <Loading />
        ) : (
          "Continue as Guest"
        )}
      </Button>
    </div>
  );
}
```

```jsx [LoginOptions.jsx]
const LoginOptions = () => {
  return (
    <div className="space-y-4">
      <Button onClick={handleGuest}>
        Continue as Guest
      </Button>
      <Button onClick={() => router.push("/login")}>
        Login or Create Account
      </Button>
    </div>
  );
};
```
:::


## Social Login (OAuth)

To initiate sign in, you can use the `initOAuth()` method from the Openfort JavaScript library and provide a `redirectTo` URL which points to a callback route.

* **Implicit flow**: that's all you need to do. The user will be taken to auth provider consent screen, and finally redirected to your app with an access and refresh token pair representing their session.
* **Pooling flow**: for example in Server-Side Auth, you need to redirect the user back to your website.

You will need to call the `initOAuth` method:

```tsx
import {OAuthProvider} from "@openfort/openfort-js";

await openfort.auth.initOAuth({
    provider: OAuthProvider.GOOGLE, // or FACEBOOK, TWITTER, etc.
    options: {
      // Depdening on the flow
      // redirectTo: 'https://your-website.com/login',
      // usePooling: true,
    },
});
```

:::note
Configure your social login providers at [your dashboard](https://dashboard.openfort.io/players/auth/providers).
Follow the guide on how to [configure social login](/docs/configuration/social-login) to learn more.
:::

Configure your social login providers from your dashboard. Follow the guide on how to [configure social login](/docs/configuration/social-login) to learn more.
The supported loginMethods are `GOOGLE`, `APPLE`, `TWITTER`, `DISCORD`, `FACEBOOK`, `LINE` or `EPIC_GAMES`.

### Implicit flow

:::code-group
```tsx [auth.tsx]
import { OAuthProvider } from '@openfort/openfort-js';
import openfort from "./openfortConfig"

function AuthButton() {
  return (
    <button onClick={async () => {
      const {url} = await openfort.auth.initOAuth({
        provider: OAuthProvider.FACEBOOK,
        options: {
          redirectTo:'https://your-website.com/login',
        },
      });
      window.location.href = url;
    }}
    >
      Continue with Facebook
    </button>
  );
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

```json [response.json]
{
  "url": "redirect-url",
  "key": "key"
}
```
:::

Now you can redirect the user to the initOAuth.url and when the process is done, you will be redirected to the redirectTo url with tokens `https://your-website.com?access_token=...&refresh_token=...&player_id=...`
You can then use those parameters to authenticate the user:

```ts
openfort.auth.storeCredentials({
    player: player_id,
    accessToken: access_token,
    refreshToken: refresh_token,
  });
```

### Pooling flow

You can pool the auth with the key returned from the initOAuth, this will check if the auth is ready every 0.5 seconds for 5 minutes sessions live for 1 hour, so you can pool the auth again if you need to.

:::code-group
```tsx [auth.tsx]
import { OAuthProvider } from '@openfort/openfort-js';
import openfort from "./openfortConfig"

function AuthButton() {
  return (
    <button onClick={async () => {
      const {key} = await openfort.auth.initOAuth({
        provider: OAuthProvider.FACEBOOK,
        options: {
          usePooling: true,
        },
      });
      await openfort.auth.poolOAuth(key);
    }}
    >
      Continue with Facebook
    </button>
  );
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

```json [response.json]
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "facebook",
              "disabled": false,
              "externalUserId": "2"
          }
      ]
  },
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJhdWQiOiJwcm9fOGY3ZTM1NTktMjhkNy00MWE2LTgxNGMtMjU0OTkzZTdkNjFkLXRlc3QiLCJleHAiOjE3MTA5ODI2MDIsImlhdCI6MTcxMDk3OTAwMiwiaXNzIjoib3BlbmZvcnQueHl6Iiwic2lkIjoiMzhhMDdmMzktMTUxOS00MjE0LWJmNmMtNzI0Zjg0ZDBiZGQwIiwic3ViIjoicGxhX2NjOWVkMmI3LWM1ZjUtNGM0My04ZGNhLWM0YjEwNGJhMTc2MiJ9.EcFtS__GwyxJu1S3tO7jMBbTCIJCpqsoNxxJrqILrKjNl2N5-SIMG2z_s2Vs8ztG6KAVy6zIp6P9GzfD7s4JiA",
  "refreshToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJzaWQiOiIzOGEwN2YzOS0xNTE5LTQyMTQtYmY2Yy03MjRmODRkMGJkZDAiLCJpYXQiOjE3MTA5NzkwMDIsImV4cCI6MTcxMzU3MTAwMn0.koNd4eoevBQQR3-z0CMGL5qVzOURZEeAgjvrHMRloLgDbScS2Qbi4W-vf2fE0fYOWUIAHnAq7cDABNwSQrEvSQ"
}
```
:::

Upon successful authentication, the SDK will return a token that can be used to authenticate the user in your application.


## Email and Password

Users often expect to sign in to your site with a password. Openfort Auth helps you implement password-based auth safely, using secure configuration options and best practices for storing and verifying passwords.

{/* Set up password for your Openfort project.

  - Enable the email provider in your [Openfort Project](https://dashboard.openfort.io/players/auth/providers)
  - Configure the Site URL and any additional redirect URLs in the [authentication management tab](/docs/dashboard/project/_/auth/url-configuration).
  - The Site URL represents the default URL that the user will be redirected to after clicking on the email signup confirmation link. */}

{/* Note: You can update the server sending email notifications and the email templates through your dashboard. Visit the guide on how to [update password authentication](/docs/configuration/password/custom-smtp) to learn more. */}

### Sign up a user

You directly receives the access token after the user confirms their email.

To sign up the user, call signUpWithEmailPassword() with their email address and password.

You can optionally specify a URL to redirect to after the user clicks the confirmation link. This URL must be configured as a Redirect URL. If you don't specify a redirect URL, the user is automatically redirected to your site URL.

:::code-group
```tsx [auth.tsx]
import openfort from "./openfortConfig"

async function signUpNewUser(email:string, password:string, firstName:string, lastName:string) {
  await openfort.auth.signUpWithEmailPassword({
    email: email,
    password: password,
    options: {
      data: {
        name: firstName + ' ' + lastName,
      },
    },
  });
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```
:::

If you want the users to verify their email, you can send them an email after sign up with:

```ts
await openfort.auth.requestEmailVerification({
    email: email,
    redirectUrl: 'http://example.com/account/register',
  });
```

### Log in a user

When your user signs in, call logInWithEmailPassword() with their email address and password:

```ts
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY"
  }
});

async function logInpUser() {
  await openfort.auth.logInWithEmailPassword({
    email: email,
    password: password
  });
}
```

Uppon successful authentication, the SDK will return a token that can be used to authenticate the user in your application.

```json response.json
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "email",
              "disabled": false,
              "verified": true,
              "email": "hello@example.com"
          }
      ]
  },
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJhdWQiOiJwcm9fOGY3ZTM1NTktMjhkNy00MWE2LTgxNGMtMjU0OTkzZTdkNjFkLXRlc3QiLCJleHAiOjE3MTA5ODI2MDIsImlhdCI6MTcxMDk3OTAwMiwiaXNzIjoib3BlbmZvcnQueHl6Iiwic2lkIjoiMzhhMDdmMzktMTUxOS00MjE0LWJmNmMtNzI0Zjg0ZDBiZGQwIiwic3ViIjoicGxhX2NjOWVkMmI3LWM1ZjUtNGM0My04ZGNhLWM0YjEwNGJhMTc2MiJ9.EcFtS__GwyxJu1S3tO7jMBbTCIJCpqsoNxxJrqILrKjNl2N5-SIMG2z_s2Vs8ztG6KAVy6zIp6P9GzfD7s4JiA",
  "refreshToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJzaWQiOiIzOGEwN2YzOS0xNTE5LTQyMTQtYmY2Yy03MjRmODRkMGJkZDAiLCJpYXQiOjE3MTA5NzkwMDIsImV4cCI6MTcxMzU3MTAwMn0.koNd4eoevBQQR3-z0CMGL5qVzOURZEeAgjvrHMRloLgDbScS2Qbi4W-vf2fE0fYOWUIAHnAq7cDABNwSQrEvSQ"
}
```

### Resetting a password (Forgot password)

#### Step 1: Create a reset password page

Create a reset password page. This page should be publicly accessible.
Collect the user's email address and request a password reset email. Specify the redirect URL, which should point to the URL of a change password page.

```ts
await openfort.auth.requestResetPassword({
  email: 'hello@example.com',
  redirectUrl: 'http://example.com/account/update-password',
})
```

#### Step 2: Create a change password page

Create a change password page at the URL you specified in the previous step. This page should be accessible only to authenticated users.
Collect the user's new password and call updateUser to update their password.

You should also pass the state parameters, which should be available in the URL of the change password page. This is to prevent CSRF attacks.

```ts
await openfort.auth.resetPassword({
  email: 'hello@example.com',
  password: 'new-password',
  state: 'verification-state',
})
```


## User Management

### The user object

Use the Auth Players page of the dashboard to manage all of your app's users and their linked accounts.

Every authenticated user with Openfort Auth results in a JSON that combines the user's information with the Openfort player `id`:

```json
    {
      "id": "pla_ff54b031-a878-4ca2-9cf5-ae190f921e9b",
      "object": "player",
      "createdAt": 1691658234,
      "linkedAccounts": [
        {
          "provider": "email",
          "email": "jaume@openfort.io",
          "disabled": false,
          "updatedAt": 1691658234
        }
      ]
    }
```

After a player has authenticated, an Openfort player `id` is created for them and is accessible through your Openfort Dashboard.

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/authenticated_players_47fca49025.png?updated_at=2023-11-09T20:08:24.682Z" alt="authenticated players" />
</div>

### Deleting users

From the user drawer, you can delete a user if necessary. This is an irreversible and destructive action although the associated player will not be deleted; if the user logs into your app again, they will have a new player id, will have to relink any formerly linked accounts, and will get a new address. Please take extreme care when deleting users.


## User Session (JWT/Authorization)

### What is a session?

A session is created when a user signs in. By default, it lasts 1 hour and a user can have an unlimited number of active sessions.

A session is represented by the Openfort Auth access token in the form of a JWT, and a refresh token which is a unique string.

Access tokens are designed to be short lived while refresh tokens never expire but can only be used once. You can exchange a refresh token only once to get a new access and refresh token pair.

This process is called **refreshing the session.**

A session terminates, depending on configuration, when:

* The user clicks sign out.
* The user changes their password or performs a security sensitive action.
* It times out due to inactivity.
* It reaches its maximum lifetime.
* A user signs in on another device.

#### Access token format

Openfort access tokens are JSON Web Tokens (JWT), signed with the ES256 algorithm. These JWTs include certain information about the user in its claims, namely:

* `sid` is the user’s current session ID
* `sub` is the user’s player Id
* `iss` is the token issuer, which should always be openfort.io
* `aud` is your Openfort app ID
* `iat` is the timestamp of when the JWT was issued
* `exp` is the timestamp of when the JWT will expire and is no longer valid. This is generally 1 hour after the JWT was issued.

### Authorizing requests with the access token

To include the current user's access token on requests to your backend, follow the instructions below. Make sure to follow the appropriate instructions if your app uses local storage.

```ts
const authToken = openfort.getAccessToken();

const response = await fetch(<your-api-route>, {
    method: <your-request-method>
    body: <your-request-body>,
    headers: {
        'Authorization': `Bearer ${accessToken}`, 
        /* Add any other request headers you'd like */
    }
});
```

<div>
  Visit our guide to [verify tokens server-side](/docs/products/server/access-token) to learn how to validate the access token on your backend.
</div>

### Log out a user

When your user logs out, call `logout()` to remove them from the browser session and any objects from localStorage.

```js
import Openfort from "@openfort/openfort-js";
const openfort = new Openfort({
  baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY"
  }
});

async function logout() {
  await openfort.auth.logout();
}
```

Upon sign out, all refresh tokens and potentially other database objects related to the affected sessions are destroyed and the client library removes the session stored in the browser.

:::note
Access tokens of revoked sessions remain valid until their expiry time, encoded in the `exp` claim. The user won't be immediately logged out and will only be logged out when the access token expires.
:::


## Export Private Key

This allows them to use their embedded wallets address with another wallet client, such as Metamask in any application.
Note that this embedded wallet is only controlling the smart account and does not hold assets in it. If you want to simply transfer ownership to a Metamask and interact with a smart contract, we'll recommend checking the [transfer ownership section](/docs/products/embedded-wallet/javascript/smart-wallet/advanced/transfer-ownership).

To have your user export their embedded wallet's private key, use the `exportPrivateKey` method from the SDK.

If your user is not `authenticated` or has not yet created an embedded wallet in your game, this method will fail.

As an example, you might attach `exportPrivateKey` as an event handler to an export wallet button in your app:

:::code-group
```tsx [ExportWalletButton.tsx]
import openfort from "./openfortConfig"

// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
function ExportWalletButton() {
  const handleExportWalletButton = async () => {
    const privateKey = await openfort.embeddedWallet.exportPrivateKey();
    console.log(privateKey);
  };

  return (
      <button onClick={handleExportWalletButton}>
        {'Export my wallet'}
      </button>
  );
}
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});
export default openfort;
```
:::

:::info
When your user exports their embedded wallet, their private key is assembled on a different origin than your app's origin. This means neither you nor Openfort can ever access your user's private key. **Your user is the only party that can ever access their full private key.**
:::


## Wallet Creation and Recovery

### Creating embedded wallets

To create wallets for your users as part of the login flow you need to set the `configureEmbeddedSigner`. The configure parameter depends on the type of recovery you want to enable in your app. Therefore, it's important to first decide the recovery method of the signer.

**Make sure to wait for the embedded state ready before using the embedded wallets. Learn more about [how to check the embedded state](/docs/products/embedded-wallet/javascript/use-openfort#waiting-for-ready).**

### Decide a recovery method

Recovering the embedded wallet is needed when a user logs into a new device or when access to the embedded wallet is lost.

Openfort embedded wallets have two core recovery modes: automatic recovery and user-based recovery. At a high-level, this setting modulates how the embedded wallet's recovery share is encrypted and stored.

* **[Automatic recovery](#automatic-recovery)**: The recovery share is encrypted with a combination of project entropy and Openfort's entropy. When logging into a new device, users can immediately access their embedded wallet.

:::tip
Before configuring the automatic recovery, generate your project's **publishable and secret shield keys** and store the **encryption share**. Learn about the differrent API keys [here](/docs/configuration/api-keys#shield-secret-and-publishable-keys).
:::

* **[User-based recovery](#user-based-recovery):** The recovery share is encrypted by **user-provided entropy**. When logging into a new device, users must enter in their password to recover the embedded wallet on the new device. Once the embedded wallet has been recovered on a device, users will not need to enter their password on that devices again.

:::info
Refer to [social recovery](/docs/products/embedded-wallet/javascript/smart-wallet/advanced/social-recovery) to make your accounts less dependent on offchain recovery methods.
:::

#### Automatic recovery

It is worth noting that while **automatic recovery** makes for smooth user UX (without needing to set up a recovery system upfront when logging in), it comes with tradeoffs. Notably, the root of trust with is in the user's authentication token. This means access to the auth token grants access to the wallet. Accordingly, this token must be properly secured at all times.

When using automatic recovery, **Shield** generates a password that is used for the encryption of the recovery share. The full encryption key can only be accessed if the decryption request includes the user's auth token.

:::warning
When using **automatic recovery**, its very important to ensure that the `encryption share` is not be available from the client side of the application.
:::

**From your backend**, you should have an endpoint that generates an encryption session for the user. This endpoint should be protected and only accessible by the user who is requesting the encryption session (i.e. the user who is logging in).

For example, in a Next.js API route, you can create an endpoint like this:

:::code-group
```ts [protected-create-encryption-session.ts]
import openfort from "./openfortAdminConfig";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const session = await openfort.registerRecoverySession(
    "YOUR_SHIELD_PUBLISHABLE_KEY",
    "YOUR_SHIELD_SECRET_KEY",
    "YOUR_SHIELD_ENCRYPTION_SHARE"
  );
  res.status(200).send({
    session: session,
  });
}
```

```ts [openfortAdminConfig.ts]
import Openfort from "@openfort/openfort-node";

const openfort = new Openfort("YOUR_OPENFORT_SECRET_KEY");

export default openfort;
```
:::

:::note
An encryption session is requested every time `configureEmbeddedSigner` is called. The encryption session is only valid for **a single use**.
:::

Once we've secured the backend we setup the client side:

##### Openfort auth

:::code-group
```tsx [configure.tsx]
import {
  ShieldAuthType,
  ShieldAuthentication,
  RecoveryMethod,
} from "@openfort/openfort-js";
import openfort from "./openfortConfig";
import getEncryptionSession from "./encryptionSession";

async function authSetAutomaticRecoveryMethod(email: string, password: string) {
  const response = await openfort.auth.signUpWithEmailPassword({
    email,
    password,
  });
  const chainId = 80002;
  const shieldAuthentication: ShieldAuthentication = {
    auth: ShieldAuthType.OPENFORT,
    token: response.token,
    encryptionSession: await getEncryptionSession(),
  };
  await openfort.embeddedWallet.configure({ chainId, shieldAuthentication });
}
```

```ts [encryptionSession.ts]
const getEncryptionSession = async (): Promise<string> => {
  try {
    const response = await fetch(
      "https://your-api-endpoint.com/api/protected-create-encryption-session",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({}),
      }
    );
    const data = await response.json();
    return data.session;
  } catch (error) {
    throw new Error("Failed to create encryption session");
  }
};
export default getEncryptionSession;
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});
export default openfort;
```
:::

##### Third party auth

This example will showcase **Firebase** as the third-party auth provider. You can replace it with any other [third-party auth provider](/docs/products/embedded-wallet/javascript/auth/external-auth).

:::code-group
```tsx [configure.tsx]
import {
  ShieldAuthType,
  ShieldAuthentication,
  ThirdPartyOAuthProvider,
  TokenType,
  RecoveryMethod,
} from "@openfort/openfort-js";
import openfort from "./openfortConfig";
import getEncryptionSession from "./encryptionSession";

async function authSetAutomaticRecoveryMethod(idToken: string) {
  await openfort.auth.authenticateWithThirdPartyProvider({
    provider: ThirdPartyOAuthProvider.FIREBASE,
    token: idToken,
    tokenType: TokenType.idToken,
  });
  const chainId = 80002;
  const shieldAuthentication = {
    auth: ShieldAuthType.OPENFORT,
    token: idToken,
    authProvider: "firebase",
    tokenType: "idToken",
    encryptionSession: await getEncryptionSession(),
  };
  await openfort.embeddedWallet.configure({ chainId, shieldAuthentication });
}
```

```ts [encryptionSession.ts]
const getEncryptionSession = async (): Promise<string> => {
  try {
    const response = await fetch(
      "https://your-api-endpoint.com/api/protected-create-encryption-session",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({}),
      }
    );
    const data = await response.json();
    return data.session;
  } catch (error) {
    throw new Error("Failed to create encryption session");
  }
};
export default getEncryptionSession;
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});
export default openfort;
```
:::

:::tip
We recommend enabling user-based recovery for users. This is especially important to enforce as the value of assets in a user's wallet grows.
:::

***

#### User-based recovery

**Password recovery**

Require that users set a password when the wallet is created, enforcing password-based recovery from the start.

If encrypted by user-provided entropy, **only the user can decrypt the recovery share**. Openfort never sees the user's password. Therefore, if you're not planning to ever user the automatic recovery mode, you can use the `encryption share` in the client side of the application.

##### Openfort auth

:::code-group
```tsx [configure.tsx]
import {
  ShieldAuthType,
  ShieldAuthentication,
  RecoveryMethod,
} from "@openfort/openfort-js";
import openfort from "./openfortConfig";

async function authSetPasswordRecoveryMethod(
  email: string,
  password: string,
  recoveryPassword: string
) {
  const response = await openfort.auth.signUpWithEmailPassword({
    email,
    password,
  });
  const chainId = 80002;
  const shieldAuthentication: ShieldAuthentication = {
    auth: ShieldAuthType.OPENFORT,
    token: response.token,
  };
  const recoveryParams = {
    password: recoveryPassword,
    recoveryMethod: RecoveryMethod.PASSWORD,
  };
  await openfort.embeddedWallet.configure({
    chainId,
    shieldAuthentication,
    recoveryParams,
  });
}
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    shieldEncryptionKey: "YOUR_SHIELD_ENCRYPTION_SHARE",
  },
});
export default openfort;
```
:::

##### Third party auth

This example will showcase **Firebase** as the third-party auth provider. You can replace it with any other third-party auth provider [supported by Openfort](/docs/products/embedded-wallet/javascript/auth/external-auth) or with [Custom Auth](/docs/configuration/custom-auth/auth-token).

:::code-group
```tsx [configure.tsx]
import {
  ShieldAuthType,
  ShieldAuthentication,
  ThirdPartyOAuthProvider,
  TokenType,
  RecoveryMethod,
} from "@openfort/openfort-js";
import openfort from "./openfortConfig";

async function authAndSetPasswordRecoveryMethod(
  idToken: string,
  password: string
) {
  await openfort.auth.authenticateWithThirdPartyProvider({
    provider: ThirdPartyOAuthProvider.FIREBASE,
    token: idToken,
    tokenType: TokenType.idToken,
  });
  const chainId = 80002;
  const shieldAuthentication: ShieldAuthentication = {
    auth: ShieldAuthType.OPENFORT,
    token: idToken,
    authProvider: "firebase",
    tokenType: "idToken",
  };
  const recoveryParams = {
    password: password,
    recoveryMethod: RecoveryMethod.PASSWORD,
  };
  await openfort.embeddedWallet.configure({
    chainId,
    shieldAuthentication,
    recoveryParams,
  });
}
```

```ts [openfortConfig.ts]
import Openfort from "@openfort/openfort-js";

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    shieldEncryptionKey: "YOUR_SHIELD_ENCRYPTION_SHARE",
  },
});
export default openfort;
```
:::

***

### Pregeneration

Openfort also allows you to pre-generate embedded wallets for your users, even before they first login to your app. Please see our [pregeneration guide](/docs/products/server/pregenerate-wallets) for more.


## Update Recovery Method

Once a wallet has been created, users have the ability to upgrade from automatic recovery to a user-owned recovery method, or to switch between different user-owned recovery methods.

### Upgrading a user's recovery method

To update the recovery method, you will need to call the `setEmbeddedRecovery`:

```tsx
await openfort.embeddedWallet.setEmbeddedRecovery({
    recoveryMethod,
    recoveryPassword,
    encryptionSession,
});
```

In order to update the recovery method, you will need to request the user for their **password**.

:::tip
Users can **reset their password** using this method as well.
:::

When calling `setEmbeddedRecovery`, then recovery method will be updated to the new method provided. The user won't be required to reconstruct their private key right after.

As an example, you might add `setEmbeddedRecovery` as an event handler for a set recovery button in your app:

:::code-group
```tsx [UpdateRecoveryButton.tsx]
import openfort from './openfortConfig';
import {RecoveryMethod} from '@openfort/openfort-js';
import getEncryptionSession from "./encryptionSession"

// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
function AddOrUpdateRecoveryButton() {
  const handleUpdateRecovery = async () => {
    const password = (
        document.querySelector(
          `input[name="password"]`
        ) as HTMLInputElement
      ).value;
    const recoveryMethod = RecoveryMethod.PASSWORD;
    const recoveryPassword = password;
    const encryptionSession = await getEncryptionSession();
    await setWalletRecovery({
      recoveryMethod,
      recoveryPassword,
      encryptionSession,
    });
  };

  return (
    <div>
      <input
        name={'password'}
        placeholder="password recovery"
      />
      <button onClick={handleUpdateRecovery}>
        {'Add recovery to your wallet'}
      </button>
    </div>
  );
}
```

```ts [encryptionSession.ts]
const getEncryptionSession = async (): Promise<string> => {
    try {
        const response = await fetch('https://your-api-endpoint.com/api/protected-create-encryption-session', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
        });
        const data = await response.json();
        return data.session;
    } catch (error) {
        throw new Error('Failed to create encryption session');
    }
};
export default getEncryptionSession;
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::


export const meta = {
  title: 'Funding wallets',
  description: 'Simplify onnramping funds to your embedded wallet.',
  subtitle: 'Simplify onnramping funds to your embedded wallet.',
}

## Funding Wallets

**Openfort makes it easy for your users to fund their wallets with a variety of assets**, including a network's native currency (e.g. ETH), USDC, and other ERC20 tokens. This makes it seamless to take onchain actions within your apps such as purchasing goods, swapping tokens, minting NFTs, and more.

<div align="center">
  <img alt="control policy spending" src="https://blog-cms.openfort.io/uploads/Funding_3d7d193386.svg" width="100%" height="100%" />
</div>

Openfort enables users to fund their wallets by:

* transferring assets from an external wallet (e.g. Rabbit Wallet)
* purchasing assets from MoonPay with fiat currency
* purchasing assets from Coinbase Onramp or transferring from Coinbase accounts

:::note
The following are three funding methods suggested from Openfort and you can find implementations of such in our SDK. You're open though to integrate any onramp.
:::

### External wallets

The **external wallets** funding option enables users to transfer funds from an external wallet (e.g. MetaMask) to their embedded wallet within your app.

:::note
With external wallets, users can fund their accounts with a network's native currency (e.g. ETH), USDC, or other ERC20 tokens.
:::

If users don't want to connect an external wallet, Openfort will also give the users to copy their embedded wallet address, and manually transfer funds from their external wallet to their embedded wallet.

### Coinbase Onramp

The [Coinbase Onramp](https://www.coinbase.com/en-es/developer-platform/products/onramp) funding option enables users to purchase assets from Coinbase or transfer assets from an existing Coinbase account, directly within your app. If users have already completed KYC and identity verification with Coinbase for an existing Coinbase account, they will not need to do so again, streamlining their asset purchase/transfer experience.

Please note that these purchases are not immediate and it may take a few minutes for funds to arrive in your user's wallet.

:::note
With Coinbase Onramp, users can fund their accounts with a network's native currency (e.g. ETH) or USDC on Coinbase's supported networks.

Note that not all payment methods are available in all regions due to local regulations. See [Coinbase's regional support guide](https://help.coinbase.com/en/commerce/getting-started/supported-payment-methods) for more information on which payment methods are supported in which regions.
:::

### MoonPay

The [MoonPay](https://www.moonpay.com/) funding option enables users to purchase assets with fiat payments including bank transfer, credit cards, and debit cards. This is particularly useful for users that may not hold crypto outside of your application and are purchasing crypto for the first time.

Please note that these purchases are not immediate, and depending on the payment method selected by your users, it may take a few days for funds to arrive in your user's wallet. Generally, paying with bank transfer has the highest approval rates for cryptocurrency purchases.

:::note
With MoonPay, users can fund their accounts with a network's native currency (e.g. ETH) or USDC on MoonPay's [supported networks](https://support.moonpay.com/customers/docs/list-of-supported-cryptocurrencies).

Note that support for assets [varies by region](https://support.moonpay.com/customers/docs/list-of-supported-cryptocurrencies) due to local regulations. If a user attempts to purchase an asset from an unsupported region, MoonPay will allow the user to purchase any assets that are supported in their region.
:::

***

### Integrating a custom fiat on-ramp

To start, you'll need to choose a fiat on-ramp provider that meets your app's requirements. Different on-ramp providers vary in their support of:

* different tokens (ETH, USDC, Dai, POL, etc.)
* different networks (Ethereum, Polygon, Optimism, etc.)
* different regions (US, Europe, Brazil, South Korea, India, etc.).
* different payment methods (credit cards, debit cards, ACH, instant ACH, etc. )

Once you have chosen an on-ramp provider for your app, set up an account with that provider and retrieve your sandbox API keys to build an integration. For example, after setting up a Moonpay account, you can retrieve your API keys from their developer dashboard like below:

Most providers will provision you with a public API key that can be exposed to your frontend, and a secret API key that should only exist on your server. Some providers may also offer a webhook API key so you can subscribe to updates on your users' transactions.

#### Integrating the provider

For the remainder of this guide, we will focus on integrating Moonpay as your fiat on-ramp provider. The integration follows three main steps:

1. Collect user details in your frontend
2. Generate the Moonpay URL with proper parameters
3. Handle the purchase flow and monitor transactions

#### 1. Collect User Information in Your Frontend

First, we need to collect information about the user and their desired purchase. Using wagmi, we can easily get the user's wallet address:

```tsx
import { useAccount } from "wagmi";

function App() {
  const { address } = useAccount();
}
```

#### 2. Generate the Moonpay URL

Once we have the user's information, we can generate the Moonpay URL. You'll need your Moonpay API key for this step:

```typescript
// Generate a unique transaction ID for tracking
const txId = 'openfort-' + window.crypto.randomUUID();

// Construct the Moonpay URL with all necessary parameters
const moonpayLink = `https://buy-sandbox.moonpay.com/` +
  `?externalTransactionId=${txId}` +
  `&apiKey=${process.env.NEXT_PUBLIC_MOONPAY_API_KEY}` +
  `&walletAddress=${address}` +
  `&currencyCode=ETH` +
  `&quoteCurrencyAmount=${fundAmount}`;
```

Important parameters in the URL:

* `externalTransactionId`: A unique identifier for tracking the transaction
* `apiKey`: Your Moonpay public API key
* `walletAddress`: The user's wallet address
* `currencyCode`: The cryptocurrency to purchase (e.g., 'ETH')
* `quoteCurrencyAmount`: The amount to purchase

#### 3. Redirect your user to the on-ramp URL

Once you have generated the Moonpay URL, you can redirect your user to complete their purchase. The following code handles the redirection and monitors the transaction status:

```typescript
const handleFund = async (service: any) => {
  // Update UI state to show progress
  setStep(StepEnum.SERVICE_PROGRESS);
  setService(service);
  
  // Open Moonpay in a new window
  window.open(service.link, '_blank');
  
  // Start monitoring the transaction
  const intervalFund = setInterval(
    () => checkFunding(() => service.checkTxResult(service.verifyUrl)),
    2000
  );
  intervalFundingId.current = intervalFund;
};

// Function to check funding status
const checkFunding = async (txResult: any) => {
  if (await txResult() === 'completed') {
    clearInterval(intervalFundingId.current);
    setStep(StepEnum.COMPLETED);
    handleSetMessage('Funds added successfully!');
  }
};

// Function to check transaction status
const checkMoonpayTransaction = async (txId: string) => {
  const verifyUrl = `https://api.moonpay.com/v1/transactions/ext/${txId}?apiKey=${process.env.NEXT_PUBLIC_MOONPAY_API_KEY}`;
  
  try {
    const response = await fetch(verifyUrl);
    if (!response.ok) return 'pending';
    
    const json = await response.json();
    switch (json[0].status) {
      case 'completed':
        return 'completed';
      case 'failed':
        return 'failed';
      default:
        return 'pending';
    }
  } catch (error) {
    console.error('Error checking transaction status:', error);
    return 'pending';
  }
};
```

:::tip
Alternatively, if you do not want to redirect the user to a new tab, you can instead surface the on-ramp URL within an **iframe** embedded within your site.
:::

**That's it! Your users can now fund the wallets they've connected/created through Openfort and take on-chain actions in your app.**


export const meta = {
  id: 'smart-wallets',
  title: 'Handling networks',
  description: 'Learn how to handle network switching and chain management with Openfort smart wallets.',
  subtitle: 'Get current network and switch between different blockchain networks',
}

## Handling Networks

The following guide will show you how to handle networks with Openfort's smart wallets using the EIP-1193 provider.

:::info
You can also use Viem's [`switchChain`](https://wagmi.sh/core/api/actions/switchChain) method with the chain ID you wish to switch to.
:::

### Get the current network

To get the current network, you can use the `eth_chainId` request (with no `params`)

:::code-group
```ts [getCurrentNetwork.ts]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = await openfort.embeddedWallet.getEthereumProvider();

const chainId = await provider.request({
  method: "eth_chainId",
  params: [],
});
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::

### Switch networks

To switch the smart wallet to a different network, send a [`wallet_switchEthereumChain`](https://docs.metamask.io/wallet/reference/wallet_switchethereumchain/) **JSON-RPC request to the wallet's EIP-1193 provider**. In the request's `params`, specify your target `chainId` as a hexadecimal string.

:::code-group
```ts [switchNetwork.ts]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = await openfort.embeddedWallet.getEthereumProvider();

await provider.request({
  method: 'wallet_switchEthereumChain',
  // Replace '0x5' with the chainId of your target network
  params: [{chainId: '0x5'}],
});
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::


export const meta = {
  id: 'auth',
  title: 'Using smart wallets',
}

## Using Smart Wallets

Smart wallets in Openfort are your primary interface for blockchain interactions. Once an embedded wallet is set up, a smart wallet is automatically created and associated for your user.

### Getting an EIP-1193 provider

All of Openfort's wallets can export a standard [EIP-1193 provider](https://eips.ethereum.org/EIPS/eip-1193) object. This allows your app to request signatures and transactions from the wallet, using familiar JSON-RPC requests like `personal_sign` or `eth_sendTransaction`.

:::info
[EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), also known as the Ethereum JavaScript API, is a standardized interface for how applications can request information, signatures, and transactions from a connected wallet.
:::

To get a wallet's EIP-1193 provider, use the openfort `getEthereumProvider` method:

:::code-group
```tsx [main.tsx]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = await openfort.embeddedWallet.getEthereumProvider();
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::

When requesting signatures and transactions from the wallet, you can either choose to interface with the **EIP-1193** provider directly, or to pass it to a library like `wagmi` or `viem`.


export const meta = {
  title: 'Integrating with web3 libraries',
  description: 'Using web3 libraries to interact with wallets and smart contracts.',
  subtitle: 'Using web3 libraries to interact with wallets and smart contracts.',
}

## Integrating with Web3 Libraries

Openfort's `wallet` object is fully compatible with popular web3 libraries for interfacing wallets, including [ethers](#ethers), [viem](#viem), and [wagmi](#wagmi).

Read below to learn how to best integrate Openfort alongside these libraries.

### Ethers

Call the wallet's `getEthereumProvider` method to get a provider:

#### Ethers v5

Ethers represents connected wallets as a [provider](https://docs.ethers.org/v5/api/providers/provider/), which can be used to take read-only actions with the wallet, and a [signer](https://docs.ethers.org/v5/api/signer/), which can be used to take write actions (signatures and transactions).

:::code-group
```tsx [client.tsx]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = openfort.embeddedWallet.getEthereumProvider();
const web3Provider = new ethers.providers.Web3Provider(provider);
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::

Then, call the provider's `getSigner` method to get the corresponding signer:

```tsx
const signer = web3Provider.getSigner();
```

You can then use the [provider](https://docs.ethers.org/v5/api/providers/provider/) and [signer](https://docs.ethers.org/v5/api/signer/) to get information about the wallet or request signatures and transactions.

#### Ethers v6

:::code-group
```tsx [client.tsx]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = openfort.embeddedWallet.getEthereumProvider();
const ethersProvider = new ethers.BrowserProvider(provider);
const signer = ethersProvider.getSigner();
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::

***

### Viem

Viem represents connected wallets as a [wallet client](https://viem.sh/docs/clients/wallet) object, which you can use to get information about the current wallet or the request signatures and transactions.

To get a viem wallet client for a user's connected wallet, first import your desired network from the `viem/chains` package and import the `createWalletClient` method and custom transport from `viem`:

```tsx
import {createWalletClient, custom} from 'viem';
// Replace `sepolia` with your desired network
import {sepolia} from 'viem/chains';
```

Lastly, get the wallet's EIP1193 provider using the wallet's `getEthereumProvider` method and pass it to viem's `createWalletClient` method like so:

:::code-group
```tsx [client.tsx]
import openfort from "./openfortConfig"
// This example assumes you have already checked that Openfort 'embeddedState' is 
// `ready` and the user is `authenticated`
const provider = await wallet.getEthereumProvider();
const walletClient = createWalletClient({
  chain: sepolia,
  transport: custom(provider),
```

```ts [openfortConfig.ts]
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

export default openfort;
```
:::

You can then use the [wallet client](https://viem.sh/docs/clients/wallet) to get information about the wallet or request signatures and transactions.

***

### Wagmi

[Wagmi](https://wagmi.sh/) is a set of React hooks for interfacing with Ethereum wallets, allowing you read wallet state, request signatures or transactions, and take read and write actions on the blockchain.

**Openfort is fully compatible with [wagmi](https://wagmi.sh/), and you can use wagmi's React hooks to interface with external and embedded wallets from Openfort. Just follow the steps below!**

:::tip
Want to start building right away?
Check out the [wagmi starter repo](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/wallet-libraries/next-wagmi).
Checkout the [wagmi live demo](https://wagmi.openfort.io).
:::

#### 1. Install dependencies

Install the latest versions of `wagmi`, `@tanstack/react-query` and `@openfort/openfort-js`:

:::code-group
```sh [npm]
npm i wagmi @tanstack/react-query @openfort/openfort-js
```

```sh [yarn]
yarn add wagmi @tanstack/react-query @openfort/openfort-js
```

```sh [pnpm]
pnpm add wagmi @tanstack/react-query @openfort/openfort-js
```
:::

#### 2. Setup TanStack Query

To start, set up your app with the [TanStack Query's React Provider](https://tanstack.com/query/v5/docs/framework/react/overview). Wagmi uses TanStack Query under the hood to power its data fetching and caching of wallet and blockchain data.

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
```

Next, create a new instance of the [`QueryClient`](https://tanstack.com/query/v4/docs/reference/QueryClient):

```tsx
const queryClient = new QueryClient();
```

Then, wrap your app's components with the [`QueryClientProvider`](https://tanstack.com/query/latest/docs/framework/react/reference/QueryClientProvider). This must be rendered inside the `WagmiProvider` component.

```tsx
<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <Connect />
  </QueryClientProvider>
</WagmiProvider>
```

For the [`client`](https://tanstack.com/query/latest/docs/framework/react/reference/QueryClientProvider) property of the `QueryClientProvider`, pass the [`queryClient`](https://tanstack.com/query/v4/docs/reference/QueryClient) instance you created.

#### 3. Setup Wagmi

To build your `wagmi` config, import the `createConfig` method. Next, import your app's required chains from [`viem/chains`](https://viem.sh/docs/development/chains/introduction.html) and the [`http`](https://wagmi.sh/core/api/transports/http#http) transport from `wagmi`.

```tsx wagmi.tsx
import { createConfig, http } from 'wagmi';
import { sepolia } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [sepolia],
  connectors: [injected()],
  transports: {
    [sepolia.id]: http(),
  },
});
```

#### 4. Create Openfort Connector

You'll need to create a custom connector for Openfort. Create a new file `openfortConnector.ts`:

```tsx main.tsx
import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
import {WagmiProvider} from 'wagmi';

import {Connect} from './components/Connect';
import {config} from './wagmi';
import {useEffect} from 'react';
import {openfortInstance} from './main';

const queryClient = new QueryClient();

export default function App() {
  useEffect(() => {
    if (!openfortInstance) return;
    openfortInstance.getEmbeddedState();
    openfortInstance.getEthereumProvider(); // EIP-6963
  }, [openfortInstance]);

  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Connect />
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

#### 5. Connector list

Create a new file `Connect.tsx` to list the available connectors and handle the connection. When you press on Openfort, then you will be redirected to the authentication page that you should implement. You can find an example of the authentication page in the [Openfort documentation](https://github.com/openfort-xyz/openfort-js/blob/main/examples/apps/wallet-libraries/vite-wagmi/src/components/Authenticate.tsx).

```tsx Connect.tsx
import * as React from 'react';
import {useNavigate} from 'react-router-dom';
import {Connector, useChainId, useConnect} from 'wagmi';

export function ConnectorsList() {
  const chainId = useChainId();
  const {connectors, connect, error} = useConnect();
  const navigate = useNavigate();
  const [activeConnector, setActiveConnector] =
    React.useState<Connector | null>(null);

  React.useEffect(() => {
    if (
      error &&
      activeConnector?.name === 'Openfort' &&
      error.message ===
        'Unauthorized - must be authenticated and configured with a signer'
    ) {
      navigate('/authentication');
    }
  }, [error, activeConnector, navigate]);

  const handleConnect = (connector: Connector) => {
    setActiveConnector(connector);
    connect({connector, chainId});
  };

  return (
    <div>
      <div className="buttons">
        {connectors
          .filter((connector) => !connector.name.includes('Injected'))
          .map((connector) => (
            <ConnectorButton
              key={connector.uid}
              connector={connector}
              onClick={() => handleConnect(connector)}
            />
          ))}
      </div>
      {error && <div className="error">Error: {error.message}</div>}
    </div>
  );
}

function ConnectorButton({
  connector,
  onClick,
}: {
  connector: Connector;
  onClick: () => void;
}) {
  const [ready, setReady] = React.useState(false);
  React.useEffect(() => {
    (async () => {
      const provider = await connector.getProvider();
      setReady(!!provider);
    })();
  }, [connector, setReady]);

  return (
    <button
      className="button"
      disabled={!ready}
      onClick={onClick}
      type="button"
    >
      {connector.name}
    </button>
  );
}
```

#### 6. Complete example

Altogether, this should look like:

:::code-group
```tsx [app.tsx]
import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
import {WagmiProvider} from 'wagmi';

import {Connect} from './components/Connect';
import {config} from './wagmi';
import {useEffect} from 'react';
import {openfortInstance} from './main';

const queryClient = new QueryClient();

export default function App() {
  useEffect(() => {
    if (!openfortInstance) return;
    openfortInstance.getEmbeddedState();
    openfortInstance.getEthereumProvider(); // EIP-6963
  }, [openfortInstance]);

  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Connect />
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

```tsx [main.tsx]
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import Openfort from '@openfort/openfort-js';
import {RouterProvider, createBrowserRouter} from 'react-router-dom';
import Authenticate from './components/Authenticate.tsx';

const OPENFORT_PUBLISHABLE_KEY = 'pk_test_505bc088-905e-5a43-b60b-4c37ed1f887a';
const SHIELD_PUBLISHABLE_KEY = 'a4b75269-65e7-49c4-a600-6b5d9d6eec66';

export const openfortInstance = new Openfort({
  baseConfiguration: {
    publishableKey: OPENFORT_PUBLISHABLE_KEY,
  },
  shieldConfiguration: {
    shieldPublishableKey: SHIELD_PUBLISHABLE_KEY,
  },
});

const router = createBrowserRouter([
  {
    path: '/',
    element: <App />,
  },
  {
    path: '/authentication',
    element: <Authenticate openfortInstance={openfortInstance} />,
  },
]);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>
);
```

```tsx [wagmi.tsx]
import {http, createConfig} from 'wagmi';
import {sepolia} from 'wagmi/chains';
import {injected} from 'wagmi/connectors';

export const config = createConfig({
  chains: [sepolia],
  connectors: [injected()],
  transports: {
    [sepolia.id]: http(),
  },
});
```

```tsx [Connect.tsx]
import * as React from 'react';
import {useNavigate} from 'react-router-dom';
import {Connector, useChainId, useConnect} from 'wagmi';

export function ConnectorsList() {
  const chainId = useChainId();
  const {connectors, connect, error} = useConnect();
  const navigate = useNavigate();
  const [activeConnector, setActiveConnector] =
    React.useState<Connector | null>(null);

  React.useEffect(() => {
    if (
      error &&
      activeConnector?.name === 'Openfort' &&
      error.message ===
        'Unauthorized - must be authenticated and configured with a signer'
    ) {
      navigate('/authentication');
    }
  }, [error, activeConnector, navigate]);

  const handleConnect = (connector: Connector) => {
    setActiveConnector(connector);
    connect({connector, chainId});
  };

  return (
    <div>
      <div className="buttons">
        {connectors
          .filter((connector) => !connector.name.includes('Injected'))
          .map((connector) => (
            <ConnectorButton
              key={connector.uid}
              connector={connector}
              onClick={() => handleConnect(connector)}
            />
          ))}
      </div>
      {error && <div className="error">Error: {error.message}</div>}
    </div>
  );
}

function ConnectorButton({
  connector,
  onClick,
}: {
  connector: Connector;
  onClick: () => void;
}) {
  const [ready, setReady] = React.useState(false);
  React.useEffect(() => {
    (async () => {
      const provider = await connector.getProvider();
      setReady(!!provider);
    })();
  }, [connector, setReady]);

  return (
    <button
      className="button"
      disabled={!ready}
      onClick={onClick}
      type="button"
    >
      {connector.name}
    </button>
  );
}
```
:::

**That's it! You've successfully integrated Openfort alongside `wagmi` in your app! 🎉**

#### 7. Use `wagmi` throughout your app

Once you've completed the setup above, you can use wagmi's React hooks throughout your app to interface with wallets and take read and write actions on the blockchain.

To use wagmi hooks, like `useAccount`, in your components, import the hook directly from `wagmi` and call it as usual:

```tsx
import {useAccount} from 'wagmi';

export default const WalletAddress = () => {
  const {address} = useAccount();
  return <p>Wallet address: {address}</p>;
}
```

#### Demo app with WAGMI

Feel free to take a look at the app's source code to see an end-to-end implementation of Openfort with wagmi:

* **[Wagmi template](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/wallet-libraries/vite-wagmi)** - Using Openfort accounts with wagmi.


import { MultiOptionDisplay } from '@/components/MCP/MultiOptionDisplay';

## Using Smart Wallets

To request signatures or transactions from a connected wallet, you can either:

* Use the wallet's EIP-1193 provider to send JSON-RPC requests to the wallet directly.
* Pass the wallet to a library like `viem`, `ethers`, or `wagmi`.
* For the embedded wallet specifically, create a `transactionIntent` from the **server** and `signMessage` it with the **embedded wallet (client)**.

:::tip[The request method]
At a high-level, the EIP-1193 provider implements a method called `request` that accepts an object with the following fields:

* **`method`**: the name of a JSON-RPC request to send to the wallet
* **`params`**: any parameters to include with the request
:::

### Signatures

Choose your preferred approach for handling wallet signatures:

<MultiOptionDisplay
  options={[
  { id: 'eip1193-signatures', label: 'EIP-1193 Provider' },
  { id: 'openfort-signatures', label: 'Openfort SDK' },
]}
/>

<span id="eip1193-signatures" className="hidden [&>*]:mb-6!">
  #### Signing Messages with EIP-1193 Provider

  The `request` method of the EIP-1193 provider can be used to request signatures. First, get the provider:

  ```tsx title="client.tsx"
  import openfort from "./openfortConfig"
  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  const provider = openfort.embeddedWallet.getEthereumProvider();
  ```

  ```ts title="openfortConfig.ts"
  import Openfort from '@openfort/openfort-js';

  const openfort = new Openfort({
    baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
    },
    shieldConfiguration: {
      shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    },
  });

  export default openfort;
  ```

  Then use the provider's `request` method with `eth_sign` or related methods:

  ```tsx
  const message = "Sign this message";
  const signature = await provider.request({
    method: 'personal_sign',
    params: [message, address]
  });
  ```

  #### Signing Typed Data with EIP-1193 Provider

  The `request` method of the EIP-1193 provider can be used to sign typed data. First, get the provider:

  ```tsx title="client.tsx"
  import openfort from "./openfortConfig"
  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  const provider = openfort.embeddedWallet.getEthereumProvider();
  ```

  Then use the provider's `request` method with `eth_signTypedData_v4`:

  ```tsx
  const address = "0x0000000000000000000000000000000000000000";

  const domain = {
    name: "Ether Mail",
    version: "1",
    chainId: 1,
    verifyingContract: "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
  };

  const types = {
    EIP712Domain: [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
      { name: "chainId", type: "uint256" },
      { name: "verifyingContract", type: "address" },
    ],
    Person: [
      { name: "name", type: "string" },
      { name: "wallet", type: "address" },
    ],
    Mail: [
      { name: "from", type: "Person" },
      { name: "to", type: "Person" },
      { name: "contents", type: "string" },
    ],
  };

  const message = {
    from: { name: "Cow", wallet: "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826" },
    to: { name: "Bob", wallet: "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB" },
    contents: "Hello, Bob!",
  };

  const signature = await provider.request({ method: "eth_signTypedData_v4",
    params: [address, JSON.stringify({ domain, types, primaryType: "Mail", message })],
  });
  ```

  #### Integration with Web3 Libraries

  If you've integrated Openfort with another web3 library, you can also use that library's syntax for requesting signatures:

  | Library | Method                                                                                             |
  | ------- | -------------------------------------------------------------------------------------------------- |
  | Ethers  | [Use the signer's `signMessage` method](https://docs.ethers.org/v5/api/signer/#Signer-signMessage) |
  | Wagmi   | [Use the `useSignMessage` hook](https://wagmi.sh/react/api/hooks/useSignMessage)                   |
  | Viem    | [Use the `signMessage` action](https://viem.sh/account-abstraction/accounts/smart/signMessage)     |

  For typed data:

  | Library | Method                                                                                                  |
  | ------- | ------------------------------------------------------------------------------------------------------- |
  | Ethers  | [Use the signer's `_signTypedData` method](https://docs.ethers.org/v5/api/signer/#Signer-signTypedData) |
  | Wagmi   | [Use the `useSignTypedData` hook](https://wagmi.sh/react/api/hooks/useSignTypedData)                    |
  | Viem    | [Use the `signTypedData` action](https://viem.sh/account-abstraction/accounts/smart/signTypedData)      |
</span>

<span id="openfort-signatures" className="hidden [&>*]:mb-6!">
  #### Signing Messages with Openfort SDK

  To request a signature from a user, use the `signMessage` method.

  When invoked, `signMessage` will request an EIP-191 [personal\_sign](https://docs.metamask.io/wallet/reference/personal_sign/) signature from the embedded wallet, and returns a Promise for the user's signature as a string.

  ```tsx title="client.tsx"
  import openfort from "./openfortConfig"

  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  async function signMessageButton(message:string) {
    await openfort.embeddedWallet.signMessage(message);
  }
  ```

  ```ts title="openfortConfig.ts"
  import Openfort from '@openfort/openfort-js';

  const openfort = new Openfort({
    baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
    },
    shieldConfiguration: {
      shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    },
  });

  export default openfort;
  ```

  #### Signing Typed Data with Openfort SDK

  To have a user sign an EIP-712 typed data signature, use the `signTypedData` method.

  When invoked, `signTypedData` will request an EIP-721 [eth\_signTypedData\_v4](https://docs.metamask.io/wallet/reference/eth_signtypeddata_v4/) signature from the embedded wallet, and returns a Promise for the user's signature as a string.

  ```tsx title="client.tsx"
  import openfort from "./openfortConfig"

  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  async function signTypedMessageButton(domain: any, types: any, value: any) {
    await openfort.embeddedWallet.signTypedData(domain, types, value);
  }
  ```
</span>

### Transactions

Choose your preferred approach for handling wallet transactions:

<MultiOptionDisplay
  options={[
  { id: 'eip1193-transactions', label: 'EIP-1193 Provider' },
  { id: 'openfort-transactions', label: 'Openfort SDK' },
]}
/>

<span id="eip1193-transactions" className="hidden [&>*]:mb-6!">
  #### Native Transactions with EIP-1193 Provider

  Get the provider and optionally configure [gas policy](/docs/configuration/gas-sponsorship) to make a sponsored transaction:

  ```tsx title="client.tsx"
  import openfort from "./openfortConfig"
  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  const provider = await openfort.embeddedWallet.getEthereumProvider({
        policy: 'pol_...',
      });
  ```

  ```ts title="openfortConfig.ts"
  import Openfort from '@openfort/openfort-js';

  const openfort = new Openfort({
    baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
    },
    shieldConfiguration: {
      shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    },
  });

  export default openfort;
  ```

  Then, using the provider's `request` method, send a [`eth_sendTransaction`](https://docs.metamask.io/wallet/reference/eth_sendtransaction/) JSON-RPC to the wallet:

  ```tsx
  const transactionRequest = {
    to: '0xRecipientAddress',
    value: 100000,
  };
  const txHash = await provider.request({
    method: 'eth_sendTransaction',
    params: [transactionRequest],
  });
  ```

  :::info
  You do not need to specify `from` as we populate it from the user's connected wallet, and you can pass either a number, bigint, or a hexadecimal string into the value parameter.
  :::

  #### Smart Contract Interactions with EIP-1193 Provider

  Calling a smart contract is a special case of sending a transaction. To call a smart contract, you should send a transaction with the following parameters:

  * **`to`**: the address of the smart contract to call
  * **`data`**: the encoded function call data
  * **`value`**: any value to send (for payable functions)

  To prepare the calldata for a smart contract interaction, we recommend using viem's [encodeFunctionData](https://viem.sh/docs/contract/encodeFunctionData#encodefunctiondata) method:

  ```tsx
  import { encodeFunctionData } from 'viem';

  const data = encodeFunctionData({
    abi: contractAbi,
    functionName: 'methodName',
    args: [arg1, arg2]
  });
  ```

  You can then send a transaction from the wallet as normal, and pass the calldata in the **`data`** field:

  ```tsx
  const transactionRequest = {
    to: '0xTheContractAddress',
    data: data,
    value: 100000, // Only necessary for payable methods
  };
  const txHash = await provider.request({
    method: 'eth_sendTransaction',
    params: [transactionRequest]
  });
  ```

  #### Batched Transactions with EIP-1193 Provider

  Smart wallets support sending a batch of transactions in a single, atomic submission to the network.

  To send batched transactions with a smart wallet, call the `wallet_sendCalls` method with a calls array of the transactions to batch together:

  ```tsx
  const txHash = await provider.request({
    method: 'wallet_sendCalls',
    params: [
      {
        calls: [
          // Approve transaction
          {
            to: USDC_ADDRESS,
            data: encodeFunctionData({
              abi: USDC_ABI,
              functionName: 'approve',
              args: ['insert-spender-address', BigInt(1e6)],
            }),
          },
          // Transfer transaction
          {
            to: USDC_ADDRESS,
            data: encodeFunctionData({
              abi: USDC_ABI,
              functionName: 'transfer',
              args: ['insert-recipient-address', BigInt(1e6)],
            }),
          },
        ],
      },
    ],
  });
  ```

  #### Integration with Web3 Libraries

  If you've integrated Openfort with another web3 library, you can also use that library's syntax for sending transactions:

  | Library | Method                                                                                                      |
  | ------- | ----------------------------------------------------------------------------------------------------------- |
  | Ethers  | Use the signer's [`sendTransaction` method.](https://docs.ethers.org/v5/api/signer/#Signer-sendTransaction) |
  | Wagmi   | Use the [`useSendTransaction` hook.](https://wagmi.sh/react/api/hooks/useSendTransaction)                   |
  | Viem    | [`sendTransaction` action](https://viem.sh/account-abstraction/actions/bundler/sendUserOperation)           |

  For batched transactions:

  | Library | Method                                                                                                    |
  | ------- | --------------------------------------------------------------------------------------------------------- |
  | Wagmi   | Use the [`useWriteContracts` hook.](https://wagmi.sh/react/api/hooks/useWriteContracts#usewritecontracts) |
  | Viem    | [`sendCalls` action](https://viem.sh/experimental/eip5792/sendCalls)                                      |
</span>

<span id="openfort-transactions" className="hidden [&>*]:mb-6!">
  #### Transaction Flow with Openfort SDK

  The Openfort SDK uses a two-step approach: create the transaction intent on the server, then sign it on the client.

  ##### 1. Create Transaction Intent on Server

  Create a request to your backend to create a transaction. In the body of the request:

  * Include the `player` that signs the transaction.
  * Include the `policy` that interacts with the contract for gas. If non-existent the user will need to have gas tokens.
  * Include `optimistic` if you want the transactions to be confirmed faster.

  #### Native Token Transfer

  Send the value of native tokens in the smallest denomination of the native currency i.e. wei (10^18) and as a `string`.

  :::tip
  The `to` parameter accepts:

  * any valid account `address` e.g. 0x680d2719F09B23F644c136Ab7336D42b6a76AdcC
  * a player `id` e.g. pla\_...
  * an account `id` e.g. acc\_...
  :::

  :::code-group
  ```bash [Curl]
  curl https://api.openfort.io/v1/transaction_intents \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player="pla_..." \
    -d policy="pol_..." \
    -d chainId=80002 \
    -d optimistic=true \
    -d "interactions[0][value]=1000" \
    -d "interactions[0][to]=pla_..."
  ```

  ```ts [Node]
  const Openfort = require('@openfort/openfort-node').default;
  const openfort = new Openfort(YOUR_SECRET_KEY);

  const playerId = "pla_...";
  const policyId = "pol_...";
  const chainId = 80002;
  const optimistic = false;

  const interaction_transfer = {
    value: "100",
    to: playerId
  };

  await openfort.transactionIntents.create({
      "player":playerId,
      "chainId":chainId,
      "optimistic":optimistic,
      "interactions":[interaction_transfer],
      "policy":policyId
    });
  ```

  ```csharp [.Net]
  string policyId = "pol_...";
  string playerId = "pla_...";
  int chainId = 80002;
  bool optimistic = false;

  var interactionTransfer = new Interaction
  (
    value: "100",
    to: playerId
  );

  var transactionIntentRequest = new CreateTransactionIntentRequest
      (
          player: playerId,
          chainId: chainId,
          policy: policyId,
          externalOwnerAddress: null!,
          optimistic: optimistic,
          confirmationBlocks: 0,
          interactions: new List<Interaction> { interactionTransfer}
      );
  await client.TransactionIntents.Create(transactionIntentRequest);
  ```
  :::

  :::info
  The `policy` used to sponsor a transaction that sends native tokens should have the `account_functions` policy rule.
  :::

  For a useful resource for computing the Wei, you can visit the [wei calculator](https://eth-converter.com/).

  #### Smart Contract Transactions

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/transaction_intents \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player="pla_..." \
    -d policy="pol_..." \
    -d chainId=80002 \
    -d optimistic=true \
    -d "interactions[0][contract]"="con_..." \
    -d "interactions[0][functionName]"="mint" \
    -d "interactions[0][functionArgs][0]"="0x63B7...484f"
  ```

  ```ts [Node]
  const Openfort = require('@openfort/openfort-node').default;
  const openfort = new Openfort(YOUR_SECRET_KEY);

  const playerId = "pla_...";
  const contractId = "con_...";
  const policyId = "pol_...";
  const chainId = 80002;
  const optimistic = false;

  const interaction_mint = {
    contract: contractId,
    functionName: "mint",
    functionArgs: [playerId],
  };

  await openfort.transactionIntents.create({
      "player":playerId,
      "chainId":chainId,
      "optimistic":optimistic,
      "interactions":[interaction_mint],
      "policy":policyId
    });
  ```

  ```csharp [.Net]
  string policyId = "pol_...";
  string contractId = "con_...";
  string playerId = "pla_...";
  int chainId = 80002;
  bool optimistic = false;

  var interactionMint = new Interaction
  (
    contract: contractId,
    functionName: "mint",
    functionArgs: new List<object> { playerId }
  );

  var transactionIntentRequest = new CreateTransactionIntentRequest
      (
          player: playerId,
          chainId: chainId,
          policy: policyId,
          optimistic: optimistic,
          interactions: new List<Interaction> { interactionMint }
      );
  await client.TransactionIntents.Create(transactionIntentRequest);
  ```
  :::

  #### Batching Transactions

  Smart accounts support batching transactions, allowing multiple actions to be rolled into one. This feature significantly simplifies Web3 interactions for your users. For example, instead of executing `approve()` and then `transfer()`, your user can perform both in a single transaction.

  For security reasons, there is a limit of 9 interactions per transaction intent.

  :::tip
  To execute a batch transaction, you can send a transaction intent with **multiple interactions**, and each interaction will be executed in the order they are received.
  :::

  :::note
  Openfort systems check the contract's ABI to find a function signature based on the `functionName` that you provide and the number of `functionArgs`.

  In the case that, in your contract, you have multiple functions with the same `functionName` and number of arguments, you can also include the `functionName` together with the argument types e.g. mint(address)
  :::

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/transaction_intents \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player="pla_...", \
    -d policy="pol_..." \
    -d chainId=80002 \
    -d optimistic=true \
    -d "interactions[0][contract]=con_..." \
    -d "interactions[0][functionName]=mint" \
    -d "interactions[0][functionArgs][0]=0x63B7...484f" \
    -d "interactions[1][contract]=con_..." \
    -d "interactions[1][functionName]=transfer" \
    -d "interactions[1][functionArgs][0]=0x32B7...213d"
  ```

  ```ts [Node]
  const Openfort = require('@openfort/openfort-node').default;
  const openfort = new Openfort(YOUR_SECRET_KEY);

  const playerId = "pla_...";
  const contractId = "con_...";
  const policyId = "pol_..."; 
  const chainId = 80002;
  const optimistic = false;

  const interaction_mint = {
    contract: contractId,
    functionName: "mint",
    functionArgs: [playerId],
  };
  const interaction_transfer = {
    contract: contractId,
    functionName: "transfer",
    functionArgs: [playerId],
  };

  await openfort.transactionIntents.create({
      "player":playerId,
      "chainId":chainId,
      "optimistic":optimistic,
      "interactions":[interaction_mint, interaction_transfer],
      "policy":policyId
    });
  ```

  ```csharp [.Net]
  string policyId = "pol_...";
  string contractId = "con_...";
  string playerId = "pla_...";
  int chainId = 80002;
  bool optimistic = false;

  var interactionMint = new Interaction
  (
    contract: contractId,
    functionName: "mint",
    functionArgs: new List<object> { playerId }
  );

  var interactionTransfer = new Interaction
  (
    contract: contractId,
    functionName: "transfer",
    functionArgs: new List<object> { playerId }
  );

  var transactionIntentRequest = new CreateTransactionIntentRequest
      (
          player: playerId,
          chainId: chainId,
          policy: policyId,
          externalOwnerAddress: null!,
          optimistic: optimistic,
          confirmationBlocks: 0,
          interactions: new List<Interaction> { interactionMint, interactionTransfer}
      );
  await client.TransactionIntents.Create(transactionIntentRequest);
  ```
  :::

  ##### 2. Sign Transaction on Client

  Use the `nextAction` returned by the backend to sign the transaction with the embedded wallet.

  The transaction will be automatically signed and broadcasted by using the `sendSignatureTransactionIntentRequest` method.

  ```js
  const handleCollectButtonClick = async () => {
    const collectResponse = await fetch(`https://your-backend.com/api/mint`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    });
    const collectResponseJSON = await collectResponse.json();

    if (collectResponseJSON.data?.nextAction) {
      // This example assumes you have already checked that Openfort 'embeddedState' is 
      // `ready` and the user is `authenticated`
      const response = await openfort.sendSignatureTransactionIntentRequest(
        collectResponseJSON.data.id,
        collectResponseJSON.data.nextAction.payload.userOperationHash
      );
      console.log("response", response);
    }
    console.log("success:", collectResponseJSON.data);
  };
  ```
</span>


## Create React App with Openfort Kit \[Get started with authentication UI elements and a wallet connector]

![openfort-kit.png](https://blog-cms.openfort.io/uploads/openfort_kit_8d6f715e38.png)

Simply run the following command to get started:

```sh Terminal
yarn create openfortkit
```

The **Openfort Kit CLI** is a command line tool that helps you quickly set up a new Openfort project with all the necessary dependencies and configurations. It allows you to customize your project by selecting different options during the setup process. You can select across:

* Framework: (Vite or Next.js)
* Auth providers: (email, socials, etc.)
* Wallet recovery method
* Theming

### Manual installation

::::steps
#### 1. Install

Start by installing [Openfort Kit](https://www.npmjs.com/package/@openfort/openfort-kit) and its peer dependencies using your package manager of choice:

:::code-group
```sh [npm]
npm install @openfort/openfort-kit wagmi viem@^2.22.0 @tanstack/react-query
```

```sh [yarn]
yarn add @openfort/openfort-kit wagmi viem@^2.22.0 @tanstack/react-query
```

```sh [pnpm]
pnpm install @openfort/openfort-kit wagmi viem@^2.22.0 @tanstack/react-query
```
:::

#### 2. Get your API keys

In the [API keys](https://dashboard.openfort.io/developers/configuration/api-keys) section of [Openfort dashboard](https://dashboard.openfort.io), you will find:

* **Publishable Key**: Safe to expose in client-side environment
* **Secret Key**: Must be kept secure and used only server-side

To generate non-custodial wallets:

1. Scroll to the Shield section and click **Create Shield keys**
2. **Store the encryption share** safely when it appears (you'll only see it once)
3. You'll receive:
   * **Shield Publishable Key**: Safe for client-side use
   * **Shield Secret Key**: Keep secure, server-side only

You will also need a walletConnect project ID. You can get one by creating a project on the [WalletConnect dashboard](https://cloud.reown.com/sign-in).

#### 3. Set up providers.

Set up providers for Wagmi, TanStack Query, and OpenfortKit.

To set up a config for Wagmi, we will use Wagmi's `createConfig` function with `@openfort/openfort-kit`'s `getDefaultConfig` function. This automatically sets up the Wagmi instance to support all chains and transports supported by Openfort. If you need more configuration go to the [Wagmi configuration guide](/docs/products/embedded-wallet/react/kit/setup//wagmi).

To set up `OpenfortKitProvider` we will need the publishable key from the Openfort dashboard, and the wallet configuration. More information on the wallet configuration can be found [here](/docs/products/embedded-wallet/react/kit/setup/provider).

:::code-group
```tsx [Providers.tsx]
"use client";

import React from "react";
import {
  AuthProvider,
  OpenfortKitProvider,
  getDefaultConfig,
  RecoveryMethod,
} from "@openfort/openfort-kit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider, createConfig } from "wagmi";
import { polygonAmoy } from "viem/chains";

const config = createConfig(
  getDefaultConfig({
    appName: "OpenfortKit demo",
    walletConnectProjectId: "YOUR_WALLET_CONNECT_PROJECT_ID",
    chains: [polygonAmoy],
    ssr: true, // Enable server-side rendering if needed
  })
);

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <OpenfortKitProvider
          // Set the publishable key of your OpenfortKit account. This field is required.
          publishableKey={"YOUR_PUBLISHABLE_KEY"}
          // Set the wallet configuration. In this example, we will be using the embedded wallet.
          walletConfig={{
            createEmbeddedSigner: true,

            embeddedSignerConfiguration: {
              shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",

              // Set the recovery method you want to use, in this case we will use the password recovery method
              recoveryMethod: RecoveryMethod.PASSWORD,

              // With password recovery we can set the encryption key to encrypt the recovery data
              // This way we don't have a backend to store the recovery data
              shieldEncryptionKey: "YOUR_SHIELD_ENCRYPTION_SHARE",
            },
          }}
        >
          {children}
        </OpenfortKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

```tsx [App.tsx]
import React from "react";
import { Providers } from "./Providers";

export default function App() {
  return <Providers>{/* Your app content */}</Providers>;
}
```
:::

Wrap your app in the `Providers` component as shown above.

#### 4. You're good to go!

Once you've configured your app, you can now use `OpenfortKitButton` to onboard your users.

```tsx page.tsx
import { OpenfortKitButton } from "@openfort/openfort-kit";

function App() {
  return (
    <div>
      <OpenfortKitButton />
    </div>
  );
}

export default App;
```
::::

### Next steps

Now that you've set up Openfort Kit, you can explore more features and customization options:

* [Configuration](/docs/products/embedded-wallet/react/kit/setup/)


import { OpenfortKitTheme } from "@/components/Openfortkit/OpenfortKitTheme";

## Openfort React SDK

<OpenfortKitTheme />

**With Openfort Kit, your app can authenticate users across web2 and web3 accounts, including:**

* **Email**, via password recovery
* **Wallet**: via Sign In With Ethereum ([SIWE](https://eips.ethereum.org/EIPS/eip-4361)) standard
* **Web2 social accounts**: via [OAuth2.0 Protocol](https://oauth.net/2/) (Google, Facebook, Twitter, Discord & more.)

You will get out of the box support for:

1. Simple UX — Give users a simple, attractive experience.
2. Multiple login methods - Email, Social, WalletConnect, and more.
3. Non-custodial embedded wallets - Secure, self-custodied signing without complexity
4. Connection with Web3 wallets
5. Beautiful Themes - Predesigned themes or full customization


## Wallets in Kit React

For a comprehensive overview of embedded wallets, wallet types, and core concepts, see the [Understanding Wallets guide](/docs/products/embedded-wallet/javascript/wallets).

This guide focuses on Kit React-specific implementation using pre-built components and hooks.

### Kit React Implementation

The Openfort Kit provides pre-built React components and hooks for embedded wallet integration, offering a declarative and developer-friendly approach to wallet management.

```typescript
import { OpenfortProvider, useOpenfort } from '@openfort/openfort-kit'

function App() {
  return (
    <OpenfortProvider
      config={{
        publishableKey: "YOUR_PUBLISHABLE_KEY",
        shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY"
      }}
    >
      <WalletComponent />
    </OpenfortProvider>
  )
}

function WalletComponent() {
  const { account, isConnected, connect } = useOpenfort()
  
  return (
    <div>
      {isConnected ? (
        <p>Connected: {account?.address}</p>
      ) : (
        <button onClick={connect}>Connect Wallet</button>
      )}
    </div>
  )
}
```

### Kit-Specific Features

The Openfort Kit provides several React-specific advantages:

#### Declarative Hooks API

React hooks that manage wallet state and provide reactive updates:

```typescript
import { 
  useOpenfort, 
  useAccount, 
  useBalance, 
  useSignMessage 
} from '@openfort/openfort-kit'

function WalletInfo() {
  const { account } = useAccount()
  const { balance } = useBalance()
  const { signMessage } = useSignMessage()
  
  const handleSign = async () => {
    const signature = await signMessage("Hello World!")
    console.log("Signature:", signature)
  }
  
  return (
    <div>
      <p>Address: {account?.address}</p>
      <p>Balance: {balance?.formatted} ETH</p>
      <button onClick={handleSign}>Sign Message</button>
    </div>
  )
}
```

#### Pre-built Components

Ready-to-use React components with built-in styling and functionality:

```typescript
import { 
  ConnectWallet, 
  WalletButton, 
  TransactionButton,
  AccountModal 
} from '@openfort/openfort-kit'

function WalletUI() {
  return (
    <div>
      <ConnectWallet />
      <WalletButton />
      <TransactionButton
        to="0x..."
        value="0.1"
        onSuccess={(hash) => console.log('Transaction:', hash)}
      />
      <AccountModal />
    </div>
  )
}
```

#### Context-Based State Management

Automatic state management across your entire React application:

```typescript
// State is automatically shared across all components
function Header() {
  const { isConnected, account } = useOpenfort()
  return <div>{isConnected ? account?.address : 'Not connected'}</div>
}

function Footer() {
  const { isConnected } = useOpenfort()
  return <div>Status: {isConnected ? 'Online' : 'Offline'}</div>
}
```

#### Built-in Error Handling

Comprehensive error handling with user-friendly messages:

```typescript
import { useOpenfortError } from '@openfort/openfort-kit'

function ErrorHandler() {
  const { error, clearError } = useOpenfortError()
  
  if (error) {
    return (
      <div className="error-banner">
        <p>{error.message}</p>
        <button onClick={clearError}>Dismiss</button>
      </div>
    )
  }
  
  return null
}
```


## Native Login With Apple

When working with Expo, you can use the [Expo AppleAuthentication](https://docs.expo.dev/versions/latest/sdk/apple-authentication/) library to obtain an ID token that you can pass to openfort-js [`authenticateThirdParty` method](#TODO).

:::info
Make sure you have configured your iOs credentials in the Openfort dashboard. Follow the [configuration steps](/docs/configuration/social-login/auth-apple#using-native-sign-in-with-apple-in-expo).
:::

Follow the [Expo docs](https://docs.expo.dev/versions/latest/sdk/apple-authentication/#installation) for installation and configuration instructions. See the [openfort-js reference](/docs/products/embedded-wallet/react-native) for instructions on initializing the openfort-js client in React Native.

```tsx ./components/Auth.native.tsx
import { Platform } from 'react-native'
import * as AppleAuthentication from 'expo-apple-authentication'
// the initialized instance of openfort-js client
import { openfort } from '../utils/openfort'

export function Auth() {
    return (
        <AppleAuthentication.AppleAuthenticationButton
        buttonType={AppleAuthentication.AppleAuthenticationButtonType.SIGN_IN}
        buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
        cornerRadius={5}
        style={{ width: 200, height: 64 }}
        onPress={async () => {
            try {
            const credential = await AppleAuthentication.signInAsync({
                requestedScopes: [
                AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
                AppleAuthentication.AppleAuthenticationScope.EMAIL,
                ],
            })
            // Sign in via Openfort Auth.
            if (credential.identityToken) {
                const {
                error,
                data: { user },
                } = await openfort.auth.loginWithIdToken({
                    provider: OAuthProvider.APPLE,
                    token: credential.identityToken,
                })
                console.log(JSON.stringify({ error, user }, null, 2))
                if (!error) {
                // User is signed in.
                }
            } else {
                throw new Error('No identityToken.')
            }
            } catch (e) {
            if (e.code === 'ERR_REQUEST_CANCELED') {
                // handle that the user cancelled the sign-in flow
            } else {
                // handle other errors
            }
            }
        }}
        />
}
```

When working with bare React Native, you can use [invertase/react-native-apple-authentication](https://github.com/invertase/react-native-apple-authentication) to obtain the ID token.


## Native Login With Google

Unlike the OAuth flow which requires the use of a web browser, the native Sign in with Google flow on Android uses the [operating system's built-in functionalities](https://developers.google.com/android/reference/com/google/android/gms/auth/api/identity/package-summary) to prompt the user for consent. Note that native sign-in has been rebranded as *One Tap sign-in on Android* by Google, which you should not confuse with *One Tap sign in for web*, as mentioned below.

When the user provides consent, Google issues an identity token (commonly abbreviated as ID token) that is then sent to your project's Openfort Auth server. When valid, a new user session is started by issuing an access and refresh token from Openfort Auth.

By default, Openfort Auth implements nonce validation during the authentication flow. This can be disabled in production under `Authentication > Providers > Google > Skip Nonce Check` in the Dashboard, or when developing locally by setting `auth.external.<provider>.skip_nonce_check`. Only disable this if your client libraries cannot properly handle nonce verification.

<div>
  Make sure you have configured your Google credentials in the Openfort dashboard. Follow the [configuration steps](/docs/configuration/social-login/auth-google).
</div>

When working with Expo, you can use the [`react-native-google-signin/google-signin` library](https://github.com/react-native-google-signin/google-signin#expo-installation) library to obtain an ID token that you can pass to openfort-js [`authenticateThirdParty` method](#TODO).

Follow the [Expo installation docs](https://react-native-google-signin.github.io/docs/setting-up/expo) for installation and configuration instructions. See the [openfort-js reference](/docs/products/embedded-wallet/react-native) for instructions on initializing the openfort-js client in React Native.

```tsx ./components/Auth.native.tsx
import {
  GoogleSignin,
  GoogleSigninButton,
  statusCodes,
} from '@react-native-google-signin/google-signin'
// the initialized instance of openfort-js client
import { openfort } from '../utils/openfort'

export default function () {
  GoogleSignin.configure({
    scopes: ['https://www.googleapis.com/auth/drive.readonly'],
    webClientId: 'YOUR CLIENT ID FROM GOOGLE CONSOLE',
  })

  return (
    <GoogleSigninButton
      size={GoogleSigninButton.Size.Wide}
      color={GoogleSigninButton.Color.Dark}
      onPress={async () => {
        try {
          await GoogleSignin.hasPlayServices()
          const userInfo = await GoogleSignin.signIn()
          if (userInfo.data.idToken) {
            const { data, error } = await openfort.auth.loginWithIdToken({
              provider: OAuthProvider.GOOGLE,
              token: userInfo.data.idToken,
            })
            console.log(error, data)
          } else {
            throw new Error('no ID token present!')
          }
        } catch (error: any) {
          if (error.code === statusCodes.SIGN_IN_CANCELLED) {
            // user cancelled the login flow
          } else if (error.code === statusCodes.IN_PROGRESS) {
            // operation (e.g. sign in) is in progress already
          } else if (error.code === statusCodes.PLAY_SERVICES_NOT_AVAILABLE) {
            // play services not available or outdated
          } else {
            // some other error happened
          }
        }
      }}
    />
  )
}
```


## Email and Password

Allow users to sign in with a password connected to their email address in your Unity game.

:::note
You can update the server sending email notifications and the email templates through your dashboard. Visit the guide on how to [update password authentication](/docs/configuration/password/custom-smtp) to learn more.
:::

### Setting up authentication

First, create a manager class to handle Openfort authentication:

```csharp
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class OpenfortAuthManager : MonoBehaviour 
{
    private OpenfortSDK openfort;
    
    private async void Start()
    {
        if (OpenfortSDK.Instance != null)
        {
            openfort = OpenfortSDK.Instance;
        }
        openfort = await OpenfortSDK.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
    }
}
```

### Sign up a new user

To register a new user with email and password:

```csharp
public class OpenfortAuthManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task SignUpNewUser(string email, string password)
    {
        try 
        {
            await openfort.auth.signUpWithEmailPassword(email, password);
            Debug.Log("User signed up successfully");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error signing up user: {e.Message}");
        }
    }

    // Optional: Send email verification
    public async Task RequestEmailVerification(string email)
    {
        try 
        {
            await openfort.auth.requestEmailVerification(email);
            Debug.Log("Verification email sent");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error sending verification email: {e.Message}");
        }
    }
}
```

### Log in a user

To authenticate an existing user:

```csharp
public class OpenfortAuthManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task LogInUser(string email, string password)
    {
        try 
        {
            var response = await openfort.auth.logInWithEmailPassword(email, password);
            Debug.Log("User logged in successfully");
            
            // The response contains:
            // - response.player: Player information
            // - response.token: Authentication token
            // - response.refreshToken: Token for refreshing authentication
            
            // Store these tokens as needed for your game
        }
        catch (Exception e)
        {
            Debug.LogError($"Error logging in: {e.Message}");
        }
    }
}
```

#### Authentication response

Upon successful authentication, you'll receive a response containing:

```json
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "email",
              "disabled": false,
              "verified": true,
              "email": "hello@example.com"
          }
      ]
  },
  "token": "eyJhbGci...",
  "refreshToken": "eyJhbGci..."
}
```

### Log out

To log out a user:

```csharp
await openfort.auth.logout();
```

### Password reset flow

For implementing a password reset flow in your Unity game:

```csharp
public class OpenfortAuthManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task RequestPasswordReset(string email)
    {
        try 
        {
            await openfort.auth.requestResetPassword(email);
            Debug.Log("Password reset email sent");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error requesting password reset: {e.Message}");
        }
    }

    public async Task ResetPassword(string email, string newPassword, string verificationState)
    {
        try 
        {
            await openfort.auth.resetPassword(email, newPassword, verificationState);
            Debug.Log("Password reset successfully");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error resetting password: {e.Message}");
        }
    }
}
```

### UI integration example

Here's a basic example of how to integrate this with Unity UI:

```csharp
public class AuthUIManager : MonoBehaviour
{
    [SerializeField] private TMP_InputField emailInput;
    [SerializeField] private TMP_InputField passwordInput;
    [SerializeField] private Button signUpButton;
    [SerializeField] private Button loginButton;
    
    private OpenfortAuthManager authManager;

    private void Start()
    {
        authManager = GetComponent<OpenfortAuthManager>();
        
        signUpButton.onClick.AddListener(HandleSignUp);
        loginButton.onClick.AddListener(HandleLogin);
    }

    private async void HandleSignUp()
    {
        await authManager.SignUpNewUser(emailInput.text, passwordInput.text);
    }

    private async void HandleLogin()
    {
        await authManager.LogInUser(emailInput.text, passwordInput.text);
    }
}
```


## External Wallet Authentication

Connect wallets via the [Sign in With Ethereum (SIWE)](https://eips.ethereum.org/EIPS/eip-4361) standard. This authentication method is designed for users who prefer to authenticate using their external wallets. Openfort's Unity integration facilitates a secure and direct authentication process using these wallets.

### Setting up wallet authentication

First, create a manager class to handle Openfort wallet authentication:

```csharp
using UnityEngine;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class OpenfortWalletManager : MonoBehaviour 
{
    private OpenfortSDK openfort;
    
    private async void Start()
    {
        openfort = await OpenfortSDK.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
    }
}
```

### Initialize SIWE authentication

To start the SIWE (Sign in With Ethereum) process:

```csharp
public class OpenfortWalletManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task InitializeSIWE(string walletAddress)
    {
        try 
        {
            await openfort.auth.initSIWE(new InitSiweRequest(walletAddress));
            Debug.Log("SIWE initialization successful");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error initializing SIWE: {e.Message}");
        }
    }
}
```

### Verify SIWE signature

After getting the signature from the wallet, verify it to authenticate the user:

```csharp
public class OpenfortWalletManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task AuthenticateWithSIWE(
        string signature, 
        string message, 
        string walletClientType, // e.g., "metamask", "coinbaseWallet"
        string connectorType)    // e.g., "wallet_connect_v2", "injected", "coinbase_wallet"
    {
        try 
        {
            var request = new AuthenticateWithSiweRequest(
                signature,
                message,
                walletClientType,
                connectorType
            );
            
            var response = await openfort.auth.authenticateWithSIWE(request);
            Debug.Log("SIWE authentication successful");
            
            // The response contains:
            // - response.player: Player information
            // - response.token: Authentication token
            // - response.refreshToken: Token for refreshing authentication
            
            // Store these tokens as needed for your game
        }
        catch (Exception e)
        {
            Debug.LogError($"Error authenticating with SIWE: {e.Message}");
        }
    }
}
```

#### Authentication response

Upon successful authentication, you'll receive a response containing:

```json
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "wallet",
              "address": "0x1234567890abcdef",
              "disabled": false,
          }
      ]
  },
  "token": "eyJhbGci...",
  "refreshToken": "eyJhbGci..."
}
```

### UI integration example

Here's a basic example of how to integrate wallet authentication with Unity UI:

```csharp
public class WalletAuthUI : MonoBehaviour
{
    [SerializeField] private Button connectWalletButton;
    [SerializeField] private TMP_Text statusText;
    
    private OpenfortWalletManager walletManager;
    private string userWalletAddress;

    private void Start()
    {
        walletManager = GetComponent<OpenfortWalletManager>();
        connectWalletButton.onClick.AddListener(HandleWalletConnection);
    }

    private async void HandleWalletConnection()
    {
        statusText.text = "Connecting wallet...";
        
        try 
        {
            // First initialize SIWE
            await walletManager.InitializeSIWE(userWalletAddress);
            
            // After getting signature from wallet (implementation depends on your wallet integration)
            string signature = await GetWalletSignature();
            string message = await GetSIWEMessage();
            
            // Authenticate
            await walletManager.AuthenticateWithSIWE(
                signature,
                message,
                "metamask", // or your chosen wallet
                "injected" // or your chosen connector type
            );
            
            statusText.text = "Wallet connected!";
        }
        catch (Exception e)
        {
            statusText.text = "Connection failed: " + e.Message;
        }
    }
}
```


## Guest Mode

:::note
User data and embedded wallets from guest sessions cannot be merged into an existing user account — guest accounts can only be upgraded into a new user account. If a guest user wants to log in with an existing account, you must delete the guest user session first.
:::

Use the `OnSignUpGuest` method from the Openfort SDK to create a guest account:

```csharp
    public async void OnSignUpGuest()
    {
        loadingPanel.SetActive(true);
        registerButton.interactable = false;
        statusTextLabel.text = $"Logging In As Guest ...";
        try
        {
            AuthResponse authResponse = await openfort.auth.signUpGuest();
            accessToken = authResponse.Token;
            await SetAutomaticRecoveryMethod();
            loginPanel.SetActive(false);
            statusTextLabel.text = $"Logged In As Guest";
            loggedinPanel.SetActive(true);
        }
        catch (System.Exception)
        {
            loginPanel.SetActive(false);
            registerPanel.SetActive(true);
        }
        signinButton.interactable = true;
        loadingPanel.SetActive(false);
    }
```

Upon successful registration, you'll receive a response containing the player information and authentication tokens:

```json
{
  "player": {
    "id": "pla_...",
    "object": "player",
    "createdAt": 1234567890,
    "linkedAccounts": []
  },
  "token": "eyJhbG...",
  "refreshToken": "eyJhbG..."
}
```

#### Upgrade a guest user to a logged-in user

Simply call [link method](/docs/products/embedded-wallet/javascript/auth/user-management/linking) to enable the guest user to upgrade their account to a logged-in account using any authentication method of their choice.


## Social Login (OAuth)

Create a script with the following code and bind it to an object.

The SDK exports a method called `AuthenticateWithOAuth` that implements the pooling OAuth flow. The method takes an `OAuthInitRequest` object as a parameter. The object contains the provider, the redirect URL, and the pooling option.

```csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class InitOpenfort : MonoBehaviour
{
    private OpenfortSDK openfort;

    async void Start()
    {
        string publishableKey = "YOUR_OPENFORT_PUBLISHABLE_KEY";
        openfort = await OpenfortSDK.Init(publishableKey);
    }

    public async void OnGoogleClicked()
    {
      OAuthInitRequest request = new OAuthInitRequest()
        {
            Provider = OAuthProvider.FACEBOOK,
            UsePooling = false,
            Options = new OAuthInitRequestOptions()
            {
                RedirectTo = "mygame://callback"
            },
        };
        await openfort.AuthenticateWithOAuth(request);
    }
}
```

Openfort is now accessible from anywhere via Openfort.Instance.

\:::warning Standalone Windows applications do not support window deep linking from a web browser to the application. Modify the request above to:

```csharp
OAuthInitRequest request = new OAuthInitRequest()
  {
      Provider = OAuthProvider.FACEBOOK,
  };
```

\:::

### Android, iOS and macOS

#### Android setup

On Android, we use [Chrome Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs/) (if available) to seamlessly connect gamers to your Openfort wallet from within the game.

<div>
  **Info: UNITY VERSIONS BELOW 2021.3**

  To check if Chrome Custom Tabs are available, older Unity versions may require a specific Gradle plugin version.
  For example, on Unity 2019.4, you must upgrade from 3.4.\* to 3.4.3 (see Android's blog post):

  1. In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Base Gradle Template under the Build section
  2. Open the newly generated Assets/Plugins/Android/baseProjectTemplate.grade file
  3. Update classpath `com.android.tools.build:gradle:3.4.0` to classpath `com.android.tools.build:gradle:3.4.3`
</div>

1. In Unity go to **Build Settings** -> **Player Settings** -> **Android** -> **Publishing Settings** -> Enable **Custom Main Manifest** and **Custom Main Gradle Template** under the **Build** section
2. Open the newly generated `Assets/Plugins/Android/AndroidManifest.xml` file. Add the following code inside the `<application>` element:

```xml
<activity
  android:name="com.openfort.unity.RedirectActivity"
  android:exported="true" >
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="mygame" android:host="callback" />
  </intent-filter>
</activity>
```

3. Open the newly generated `Assets/Plugins/Android/mainTemplate.gradle` file. Add the following code inside `dependencies` block:

```gradle
implementation('androidx.browser:browser:1.5.0')
```

:::into
For this version of the Chrome Custom Tabs to work, the compileSdkVersion must be at least 33. This is usually the same value as the targetSdkVersion, which you can set in **Build Settings** -> **Player Settings** -> **Android** -> **Other Settings** -> **Target API Level**.
:::

**Proguard**

If you enable **Minify** in your project settings, you will need to add a custom Proguard file to your project.

1. In Unity go to **Build Settings** -> **Player Settings** -> **Android** -> **Publishing Settings** -> Enable **Custom Proguard File** under the **Build** section
2. Open the newly generated Assets/Plugins/Android/proguard-user.txt file. Add the following code inside the `<application>` element

```txt
-dontwarn com.openfort.**
-keep class com.openfort.** { *; }
-keep interface com.openfort.** { *; }

-dontwarn androidx.**
-keep class androidx.** { *; }
-keep interface androidx.** { *; }
```

The application will now open when the device processes any link that starts with `mygame://callback`.

#### iOS setup

1. In Unity go to **Build Settings** -> **Player Settings** -> **iOS** -> **Other Settings** -> **Supported URL schemes**.
2. Increment the **Size** number.
3. Add your URL scheme in the **Element** field, e.g. if the deeplink URL is `mygame://callback`, add the scheme `mygame` to the field.

Uppon successful authentication, the SDK will return a token that can be used to authenticate the user in your application.

```json response.json
{
  "player": {
      "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
      "object": "player",
      "createdAt": 1710976453,
      "linkedAccounts": [
          {
              "provider": "facebook",
              "disabled": false,
              "externalUserId": "2"
          }
      ]
  },
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJhdWQiOiJwcm9fOGY3ZTM1NTktMjhkNy00MWE2LTgxNGMtMjU0OTkzZTdkNjFkLXRlc3QiLCJleHAiOjE3MTA5ODI2MDIsImlhdCI6MTcxMDk3OTAwMiwiaXNzIjoib3BlbmZvcnQueHl6Iiwic2lkIjoiMzhhMDdmMzktMTUxOS00MjE0LWJmNmMtNzI0Zjg0ZDBiZGQwIiwic3ViIjoicGxhX2NjOWVkMmI3LWM1ZjUtNGM0My04ZGNhLWM0YjEwNGJhMTc2MiJ9.EcFtS__GwyxJu1S3tO7jMBbTCIJCpqsoNxxJrqILrKjNl2N5-SIMG2z_s2Vs8ztG6KAVy6zIp6P9GzfD7s4JiA",
  "refreshToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNmODNlMTM1N2VlZmI4YmRmMTU0Mjg1MGQ2NmQ4MDA3ZDYyMGU0MDUwYjU3MTVkYzgzZjRhOTIxZDM2Y2U5Y2U0N2QwZDEzYzVkODVmMmIwZmY4MzE4ZDI4NzdlZWMyZjYzYjkzMWJkNDc0MTdhODFhNTM4MzI3YWY5MjdkYTNlIn0.eyJzaWQiOiIzOGEwN2YzOS0xNTE5LTQyMTQtYmY2Yy03MjRmODRkMGJkZDAiLCJpYXQiOjE3MTA5NzkwMDIsImV4cCI6MTcxMzU3MTAwMn0.koNd4eoevBQQR3-z0CMGL5qVzOURZEeAgjvrHMRloLgDbScS2Qbi4W-vf2fE0fYOWUIAHnAq7cDABNwSQrEvSQ"
}
```


## Third-party authentication

Openfort's embedded signers are fully compatible with any authentication provider that supports JWT-based, stateless authentication. This guide will show you how to integrate third-party authentication providers in your Unity game.

Follow the guide on how to [configure third party auth](/docs/configuration/external-auth) to learn more.
The supported loginMethods are `'accelbyte'`, `'custom'`, `'firebase'`, `'supabase'`, `'lootlocker'`, `'playfab'`, and `'oidc'`.

### Basic Setup

First, create a manager class to handle Openfort authentication:

```csharp
using UnityEngine;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class OpenfortAuthManager : MonoBehaviour 
{
    private OpenfortSDK openfort;
    
    private async void Start()
    {
        openfort = await OpenfortSDK.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
    }
}
```

### Authenticate with third-party provider

Here's how to authenticate using a third-party provider:

{/* Note: To make these instructions concrete, this guide uses Firebase as a sample third party auth provider that you can integrate alongside Openfort. */}

```csharp
public class OpenfortAuthManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task AuthenticateWithProvider(string token)
    {
        try 
        {
            var request = new ThirdPartyProviderRequest(
                ThirdPartyOAuthProvider.Firebase, // Or other provider
                token,
                TokenType.IdToken    // Or TokenType.CustomToken
            );
            
            var response = await openfort.auth.authenticateWithThirdPartyProvider(request);
            Debug.Log("Third-party authentication successful");
            
            // Handle successful authentication
            HandleAuthenticationSuccess(response);
        }
        catch (Exception e)
        {
            Debug.LogError($"Authentication error: {e.Message}");
        }
    }

    private void HandleAuthenticationSuccess(PlayerResponse response)
    {
        // response.id contains the player ID
        // response.linkedAccounts contains the linked provider accounts
        Debug.Log($"Authenticated player ID: {response.Id}");
    }
}
```

#### Authentication response

Upon successful authentication, you'll receive a response containing:

```json
{
  "id": "pla_cc9ed2b7-c5f5-4c43-8dca-c4b104ba1762",
  "object": "player",
  "createdAt": 1710976453,
  "linkedAccounts": [
      {
          "provider": "firebase",
          "disabled": false,
          "externalUserId": "2"
      }
  ]
}
```

### Example

#### [Firebase Auth w/ Unity Android](https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer)

An integration with Google Play Games using Firebase Auth as a third party auth provider.

export const examples = [
  {
    name: 'Firebase Auth w/ Unity Android',
    description: 'An integration with Google Play Games using Firebase Auth as a third party auth provider.',
    href: 'https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer'
  }
]


## User Session Management

Here's a complete example of managing sessions in Unity:

```csharp
using UnityEngine;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class SessionManager : MonoBehaviour 
{
    private OpenfortSDK openfort;
    
    private async void Start()
    {
        openfort = await OpenfortSDK.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
    }

    // Get the current access token
    public async Task<string> GetAccessToken()
    {
        try 
        {
            string accessToken = await openfort.GetAccessToken();
            return accessToken;
        }
        catch (Exception e)
        {
            Debug.LogError($"Error getting access token: {e.Message}");
            return null;
        }
    }

    // Using the access token for API requests
    public async Task MakeAuthenticatedRequest(string endpoint)
    {
        try 
        {
            string accessToken = await GetAccessToken();
            
            // Example using UnityWebRequest
            using (UnityWebRequest request = UnityWebRequest.Get(endpoint))
            {
                request.SetRequestHeader("Authorization", $"Bearer {accessToken}");
                await request.SendWebRequest();
                
                if (request.result == UnityWebRequest.Result.Success)
                {
                    string response = request.downloadHandler.text;
                    // Handle response
                }
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"API request failed: {e.Message}");
        }
    }

    // Logout functionality
    public async Task LogoutUser()
    {
        try 
        {
            await openfort.auth.logout();
            Debug.Log("User logged out successfully");
            
            // Additional cleanup if needed
            // For example, return to login screen
            SceneManager.LoadScene("LoginScene");
        }
        catch (Exception e)
        {
            Debug.LogError($"Logout error: {e.Message}");
        }
    }
}
```


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Setup game ads to sponsor gas fees

### Overview

This sample project showcases the Openfort integration with [Unity LevelPlay](https://docs.unity.com/monetization-dashboard/en-us/manual/UnityLevelPlay).

The sample includes:

* [**`ugs-backend`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

  A .NET Core project with [Cloud Code C# modules](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules#Cloud_Code_C#_modules) that implement [Openfort C# SDK](https://www.nuget.org/packages/Openfort.SDK/1.0.21) methods. Needs to be hosted in Unity Gaming Services.

* [**`unity-client`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

  A Unity sample game that connects to `ugs-backend` through [Cloud Code](https://docs.unity.com/ugs/manual/cloud-code/manual). It uses [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) to have full compatibility with `ugs-backend` responses.

<VideoSnippet title="Video" src="vjjvDILS-DU" />

### Application Workflow

<div align="center">
  <img alt="Integration workflow" src="https://blog-cms.openfort.io/uploads/unity_ads_sample_workflow_7b897e13de.png" width="100%" height="100%" />
</div>

### Prerequisites

* **Get started with Openfort**

  * [Sign in](https://dashboard.openfort.io/login) or [sign up](https://dashboard.openfort.io/register) and create a new dashboard project

* **Get started with UGS**

  * [Complete basic prerequisites](https://docs.unity.com/ugs/manual/overview/manual/getting-started#Prerequisites)

* **Get started with ironSource**:
  * [Sign up](https://developers.is.com/ironsource-mobile/air/sign-up-ironsource/) on the ironSource website

### Set up Openfort dashboard

* [Add an NFT contract](https://dashboard.openfort.io/contracts/new)

  This sample requires an NFT contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (contract deployed in 80002 Amoy). You can use it for this tutorial too:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_4_9397f3633b.png?updated_at=2023-12-14T15:59:33.808Z" alt="Contract Info" />
  </div>

* [Add an ERC20 contract](https://dashboard.openfort.io/contracts/new)

  This sample also requires an ERC20 contract to run. You can [deploy a standard one](https://thirdweb.com/thirdweb.eth/TokenERC20) and then add it to the Openfort dashboard following the same logic as above.

* [Add a Full Sponsor Policy](https://dashboard.openfort.io/policies/new)

  We aim to cover gas fees for our players when they mint the NFT (if they have watched the ad video). Set a new gas policy for that:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_5_ab3d8ad48d.png?updated_at=2023-12-14T15:59:33.985Z" alt="Gas Policy" />
  </div>

  Add a rule so the NFT contract uses this policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="NFT Policy Rule" />
  </div>

  Add also a rule for the ERC20 contract, as we want to send some ERC20 tokens to the player to be able to test the sample:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_22_aec7863428.png?updated_at=2023-12-31T16:02:32.817Z" alt="ERC20 Policy Rule" />
  </div>

* [Add a Fixed Charge Policy](https://dashboard.openfort.io/policies/new)

  The players will be charged with 1 in-game ERC20 token when they decide not to watch the ad:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample18_2b75d93690.png?updated_at=2024-01-14T18:31:55.626Z" alt="Fixed charge policy" />
  </div>

  Add a rule so the policy applies to the NFT contract:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="NFT Policy Rule" />
  </div>

* [Add a Backend wallett](https://dashboard.openfort.io/accounts)

  Enter a name and choose ***Add account***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_23_74b85444b2.png?updated_at=2023-12-31T16:09:09.921Z" alt="Developer account" />
  </div>

  This will automatically create a custodial wallet that we'll use to send the ERC20 tokens to the players. **IMPORTANT: Transfer a good amount of tokens from the created ERC20 contract to this wallet to facilitate testing**.

### Set up ironSource

* #### Get Unity Cloud keys

  Before going into ironSource, go to the [Unity Cloud dashboard](https://cloud.unity.com/) and open ***Unity Ads Monetization*** using *Shortcuts*:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample19_7bf501e9a9.png?updated_at=2024-01-14T21:56:19.185Z" alt="Unity Cloud dashboard: Unity Ads Monetization" />
  </div>

  * ##### Create a LevelPlay Service Account

    Now go to the ***API management*** section and choose ***Create LevelPlay Service Account***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample12_c2ec3e5dd7.png?updated_at=2024-01-08T17:25:19.881Z" alt="Unity Cloud dashboard: Create LevelPlay Service Account" />
    </div>

    Copy and save the ***Key ID*** and the ***Secret key*** somewhere safe and choose ***Done***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample13_adb919080c.png?updated_at=2024-01-08T17:25:19.985Z" alt="Unity Cloud dashboard: Copy LevelPlay Service Account credentials" />
    </div>

  * ##### Get Monetization Stats API Access

    Copy and save the API Key. Choose ***Create API Key*** if it's not already there:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample31_1139cc3e32.png?updated_at=2024-01-14T22:10:25.975Z" alt="Unity Cloud dashboard: copy Monetization Stats API key" />
    </div>

  * ##### Get Organization Core ID

    Copy and save the Organization Core ID:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample32_07789b5094.png?updated_at=2024-01-14T22:10:08.028Z" alt="Unity Cloud dashboard: copy Organization Core ID" />
    </div>

* #### Create an ironSource LevelPlay app

  Go to the [ironSource dashboard](https://platform.ironsrc.com/partners/dashboard) and under the *LevelPlay* section, choose ***Add app*** and enter your app details:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample1_a6eae902d4.png?updated_at=2024-01-08T15:23:19.695Z" alt="ironSource: new app" />
  </div>

  Select the following settings and choose ***Add app***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample2_07485439ba.png?updated_at=2024-01-08T15:31:25.290Z" alt="ironSource: app details" />
  </div>

  Activate ***Rewarded Video*** as an ad unit and choose ***Continue***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample3_2acaeaa57e.png?updated_at=2024-01-08T15:36:02.386Z" alt="ironSource: activate ad units" />
  </div>

* #### Set up SDK Networks

  In the *Available Networks* panel select ***Unity Ads***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample4_549e6a7164.png?updated_at=2024-01-08T15:48:55.693Z" alt="ironSource: available networks" />
  </div>

  Enable the ***Unity bidder auto-setup*** option, add all the credentials from the [*Get Unity Cloud keys* section](https://github.com/openfort-xyz/unity-ad-sample#get-unity-cloud-keys) and choose ***Save***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample5_41d6ab375c.png?updated_at=2024-01-08T17:32:19.205Z" alt="ironSource: adding Unity Ads" />
  </div>

  {" "}

  *Unity Ads* will have appeared as a new available network. Choose ***Setup***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample14_d57379d965.png?updated_at=2024-01-08T17:49:05.283Z" alt="ironSource: setup Unity Ads" />
  </div>

  Because we enabled the *Unity bidder auto-setup* option, now you can choose ***Add bidder***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample15_eecec77e16.png?updated_at=2024-01-08T17:49:05.583Z" alt="ironSource: add bidder" />
  </div>

  The needed information from Unity will be automatically retrieved. Choose ***Save***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample16_5141cc4b35.png?updated_at=2024-01-08T17:49:05.590Z" alt="ironSource: save app" />
  </div>

### Set up Unity Cloud

Thanks to the *Unity bidder auto-setup* option, a new project has been automatically created in the [Unity Cloud dashboard](https://cloud.unity.com/). Now your LevelPlay Service Account needs to have some admin roles over this newly created project. Go to ***Administration --> Service accounts*** and choose your account:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample20_9dea7b262c.png?updated_at=2024-01-14T21:56:23.784Z" alt="Set up Unity Cloud: service account" />
</div>

Scroll down and choose ***Manage project roles***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample21_50cb464fa0.png?updated_at=2024-01-14T21:56:23.788Z" alt="Set up Unity Cloud: manage project roles" />
</div>

Select your project and choose ***Next***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample22_980d7e7834.png?updated_at=2024-01-14T21:56:23.877Z" alt="Set up Unity Cloud: select project" />
</div>

In the *Admin* dropdown select:

* ***Player Resource Policy Editor***
* ***Project Resource Policy Editor***
* ***Unity Environments Admin***

In the *LiveOps* dropdown select:

* ***Cloud Code Script Publisher***
* ***Triggers Configuration Editor***
* ***Leaderboards Admin***
* ***Cloud Code Editor***

Choose ***Save***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample23_b8f548f685.png?updated_at=2024-01-14T21:56:23.983Z" alt="Set up Unity Cloud dashboard: add roles" />
</div>

### Set up [`ugs-backend`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

* #### Set Openfort dashboard variables

  Open the [solution](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules.sln) with your preferred IDE, open [`SingletonModule.cs`](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/SingletonModule.cs) and fill in these variables:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample24_bbba67daca.png?updated_at=2024-01-14T21:56:19.781Z" alt="Singleton Module" />
  </div>

  * `OfApiKey`: [Retrieve the **Openfort secret key**](https://dashboard.openfort.io/developers/configuration/api-keys)
  * `OfNftContract`: [Retrieve the **NFT contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfGoldContract`: [Retrieve the **ERC20 contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfFullSponsorPolicy`: [Retrieve the **Full Sponsor Policy API ID**](https://dashboard.openfort.io/policies)
  * `OfChargeErc20Policy`: [Retrieve the **Fixed Charge Policy API ID**](https://dashboard.openfort.io/policies)
  * `OfDevAccount`: [Retrieve the **Developer Account API ID**](https://dashboard.openfort.io/accounts)

* #### Package Code
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Package_code).

* #### Deploy to UGS
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Deploy_a_module_project).

### Set up [`unity-client`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

In Unity go to *Edit --> Project Settings --> Services* and link the `unity-client` to your UGS Project:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample25_61a831c3fe.png?updated_at=2024-01-14T21:56:23.781Z" alt="Services settings" />
</div>

Select your *Environment*:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample26_230b3e9819.png?updated_at=2024-01-14T21:56:22.480Z" alt="UGS environment" />
</div>

Under *Assets --> Scripts --> Controllers* open the ***AdsController.cs***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample27_45abf61c4b.png?updated_at=2024-01-14T21:56:14.982Z" alt="AdsController.cs" />
</div>

Fill the **`appKey`** variable with the *ironSource LevelPlay app key* and save the script:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample29_731247fac0.png?updated_at=2024-01-14T21:56:24.804Z" alt="ironSource LevelPlay app key" />
</div>

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample28_0ead9e68e7.png?updated_at=2024-01-14T21:56:19.186Z" alt="ironSource LevelPlay app key" />
</div>

### Build to Android

In Unity go to [*Android Player settings*](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html) and make sure *Other Settings* looks like this:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_7_e6ec7eb903.png?updated_at=2023-12-28T07:47:59.386Z" alt="Android Player settings" />
</div>

Also, make sure to sign the application with a [Keystore](https://docs.unity3d.com/Manual/android-keystore-create.html) in *Publishing Settings*:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_8_ecae38df0e.png?updated_at=2023-12-28T07:47:59.307Z" alt="Application Signing" />
</div>

Return to *Build Settings* and choose ***Build***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_ads_sample30_2b8dbf10b8.png?updated_at=2024-01-14T22:13:25.912Z" alt="Build" />
</div>

Send and run the *.apk* on your device.

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and [Unity LevelPlay](https://docs.unity.com/monetization-dashboard/en-us/manual/UnityLevelPlay). Always remember to test every feature before deploying to guarantee a flawless player experience.

For a deeper understanding of the underlying processes, check out the [tutorial video](https://www.youtube.com/watch?v=vjjvDILS-DU).

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/iap-unity-sample/issues).

If you have questions, or comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Integrate Android In-App Purchases (IAP) in Unity

### Overview

This sample project showcases the Openfort integration with Android [In-App Purchasing](https://docs.unity3d.com/Packages/com.unity.purchasing@4.10/manual/Overview.html) in Unity.

The sample includes:

* [**`ugs-backend`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

  A .NET Core project with [Cloud Code C# modules](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules#Cloud_Code_C#_modules) that implement [Openfort C# SDK](https://www.nuget.org/packages/Openfort.SDK/1.0.21) methods. Needs to be hosted in Unity Gaming Services.

* [**`unity-client`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

  A Unity sample game that connects to `ugs-backend` through [Cloud Code](https://docs.unity.com/ugs/manual/cloud-code/manual). It uses [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) to have full compatibility with `ugs-backend` responses.

<VideoSnippet title="Video" src="8Pw4VUyWVY8" />

### Application Workflow

<div align="center">
  <img alt="Integration workflow" src="https://blog-cms.openfort.io/uploads/unity_iap_sample_workflow_7f84b68e28.png" width="100%" height="100%" />
</div>

### Workflow

1. [Sign in as a new anonymous player](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/AuthController.cs#L44)
2. [Create an Openfort player](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/PlayersModule.cs#L59) and a [custodial account](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/PlayersModule.cs#L66)
3. [Save the Openfort player's information](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/PlayersModule.cs#L72) to the Unity player's dashboard
4. [Initialize Unity In-App Purchasing service](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/ShopController.cs#L44)
5. Now the player can [purchase a consumable or a non-consumable in-app product](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/ShopController.cs#L74)
6. [If the consumable purchase is successful](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/ShopController.cs#L124), some [ERC20 tokens will be transferred](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/TransferModule.cs#L31) to its account
7. [If the non-consumable purchase is successful](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/ShopController.cs#L127), the player will [mint an NFT](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/MintingModule.cs#L25)
8. The player can also [retrieve their ERC20 token balance](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/InventoryController.cs#L56) and [NFT inventory](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/Scripts/Controllers/InventoryController.cs#L24)

### Prerequisites

* **Get started with Openfort**

  * [Sign in](https://dashboard.openfort.io/login) or [sign up](https://dashboard.openfort.io/register) and create a new dashboard project

* **Get started with UGS**

  * [Complete basic prerequisites](https://docs.unity.com/ugs/manual/overview/manual/getting-started#Prerequisites)
  * [Create a project](https://docs.unity.com/ugs/manual/overview/manual/getting-started#CreateProject)

* **Get started with Google Play Console**
  * [Create and set up your app](https://support.google.com/googleplay/android-developer/answer/9859152?hl=en)

### Setup Openfort dashboard

* [Add an NFT contract](https://dashboard.openfort.io/contracts/new)

  This sample requires an NFT contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (contract deployed in 80002 Amoy). You can use it for this tutorial too:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_4_9397f3633b.png?updated_at=2023-12-14T15:59:33.808Z" alt="Contract Info" />
  </div>

* [Add an ERC20 contract](https://dashboard.openfort.io/contracts/new)

  This sample also requires an ERC20 contract to run. You can [deploy a standard one](https://thirdweb.com/thirdweb.eth/TokenERC20) and then add it to the Openfort dashboard following the same logic as above.

* [Add a Policy](https://dashboard.openfort.io/policies/new)

  We aim to cover gas fees for our users when they mint the NFT. Set a new gas policy for that:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_5_ab3d8ad48d.png?updated_at=2023-12-14T15:59:33.985Z" alt="Gas Policy" />
  </div>

  Add a rule so the NFT contract uses this policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="NFT Policy Rule" />
  </div>

  Add also a rule for the ERC20 contract:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_22_aec7863428.png?updated_at=2023-12-31T16:02:32.817Z" alt="ERC20 Policy Rule" />
  </div>

* [Add a Backend wallet](https://dashboard.openfort.io/accounts)

  Enter a name and choose ***Add account***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_23_74b85444b2.png?updated_at=2023-12-31T16:09:09.921Z" alt="Developer account" />
  </div>

  This will automatically create a custodial wallet that we'll use to send the ERC20 tokens to the players. **IMPORTANT: Transfer a good amount of tokens from the created ERC20 contract to this wallet to facilitate testing**.

### Set up [`ugs-backend`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

* #### Set Openfort dashboard variables

  Open the [solution](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules.sln) with your preferred IDE, open [`SingletonModule.cs`](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/SingletonModule.cs) and fill in these variables:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_2_b14ed6e743.png?updated_at=2023-12-31T16:17:12.709Z" alt="Singleton Module" />
  </div>

  * `OfApiKey`: [Retrieve the **Openfort secret key**](https://dashboard.openfort.io/developers/configuration/api-keys)
  * `OfNftContract`: [Retrieve the **NFT contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfGoldContract`: [Retrieve the **ERC20 contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfSponsorPolicy`: [Retrieve the **Policy API ID**](https://dashboard.openfort.io/policies)
  * `OfDevAccount`: [Retrieve the **backend wallet API ID**](https://dashboard.openfort.io/accounts)

* #### Package Code
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Package_code).

* #### Deploy to UGS
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Deploy_a_module_project).

### Set up [`unity-client`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

In Unity go to *Edit --> Project Settings --> Services* and link the `unity-client` to your UGS Project:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_16_c1ac7c4b45.png?updated_at=2023-12-28T15:52:03.478Z" alt="Services settings" />
</div>

Select your *Environment*:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_17_e60d56f379.png?updated_at=2023-12-28T15:52:03.577Z" alt="UGS environment" />
</div>

Now make sure *In-App Purchasing* is enabled and *Current Targeted Store* is set to ***Google Play***. Then follow the instructions to set the **Google Play License Key** to your UGS project:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_18_3c78605c09.png?updated_at=2023-12-28T15:52:03.586Z" alt="Google Play License Key" />
</div>

Your UGS project dashboard should look like this:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_19_6802cc268e.png?updated_at=2023-12-28T15:52:04.490Z" alt="License key in UGS dashboard" />
</div>

### Test in Editor

Play the **Main** scene and you should see the sign-in panel:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_20_8940611454.png?updated_at=2024-01-02T12:23:00.990Z" alt="Sign in panel" />
</div>

Choose ***Sign in***. The first time it will create a new player but the next time it will sign in as the same player. After some authentication-related logs, this panel should appear:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_3_478298f237.png?updated_at=2023-12-27T11:22:46.793Z" alt="Game Scene" />
</div>

Here you have two options:

* Purchase ERC20 tokens (x10)
* Purchase NFT

By clicking any of them, a *Fake Store* panel will pop up, letting you confirm or cancel the purchase:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_4_a04e9420ed.png?updated_at=2023-12-27T15:44:43.689Z" alt="Game Scene" />
</div>

If you confirm, after a brief period you should see the *Transaction successful* message:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_5_ac991ecb2a.png?updated_at=2023-12-27T15:48:49.186Z" alt="Game Scene" />
</div>

You can then click on the inventory icon to see the representation of your on-chain assets:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_6_fd93f3f3a2.png?updated_at=2023-12-27T15:51:49.900Z" alt="Game Scene" />
</div>

In the [Openfort Players dashboard](https://dashboard.openfort.io/players), a new player entry should be visible. On selecting this player:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_opensea_img_34_706b0d267e.png?updated_at=2023-11-19T11:06:46.177Z" alt="Player Entry" />
</div>

You'll notice that a `mint` transaction has been successfully processed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_7_75cf7a4264.png?updated_at=2023-12-14T16:05:01.500Z" alt="Mint Transaction" />
</div>

Additionally, by choosing your **Amoy Account** and viewing ***NFT Transfers***, the transaction is further confirmed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_8_6b345bd148.png?updated_at=2023-12-14T16:05:00.991Z" alt="Etherscan" />
</div>

### Build App Bundle

In Unity go to [*Android Player settings*](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html) and make sure *Other Settings* looks like this:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_7_e6ec7eb903.png?updated_at=2023-12-28T07:47:59.386Z" alt="Android Player settings" />
</div>

Also, make sure to sign the application with a [Keystore](https://docs.unity3d.com/Manual/android-keystore-create.html) in *Publishing Settings*:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_8_ecae38df0e.png?updated_at=2023-12-28T07:47:59.307Z" alt="Application Signing" />
</div>

Then go to *Build Settings*, check ***Build App Bundle (Google Play)*** and choose ***Build***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_9_6d1e1a5636.png?updated_at=2023-12-28T07:52:15.586Z" alt="Build" />
</div>

### Set up Google Play Console

* #### Create internal release

  On your [Google Play Console](https://play.google.com/console/u/0/developers/7556582789169418933?onboardingflow=signup) app, go to *Release --> Testing --> Internal testing --> Testers* and select or create an email list with the emails that will test your app. Then choose ***Create new release***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_10_f700f82ef1.png?updated_at=2023-12-28T15:07:32.491Z" alt="New release" />
  </div>

  Upload the `.aab` file and then choose ***Next***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_11_06459575df.png?updated_at=2023-12-28T15:07:33.382Z" alt="Upload build" />
  </div>

  If needed, solve pending errors and warnings and then choose ***Save and publish***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_12_da52624cb6.png?updated_at=2023-12-28T15:07:32.481Z" alt="Save and publish" />
  </div>

* #### Import IAP catalog

  On your [Google Play Console](https://play.google.com/console/u/0/developers/7556582789169418933?onboardingflow=signup) app, go to *Monetize --> Products --> In-app products* and choose ***Import***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_13_04a57f78c6.png?updated_at=2023-12-28T15:07:32.484Z" alt="Create product" />
  </div>

  Upload the [`GooglePlayProductCatalog.csv`](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/GooglePlayProductCatalog.csv) file (which contains all the in-app products) and choose ***Import***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_14_9a114af583.png?updated_at=2023-12-28T15:07:32.397Z" alt="Import products" />
  </div>

  You should see all the products have been created:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_15_45877d642d.png?updated_at=2023-12-28T15:07:32.278Z" alt="Products created" />
  </div>

### Test in Android

Once the internal testing release is published, you have two options to test:

* Build and run the .apk directly to your device ([if the *version number* is the same as in the internal release](https://docs.unity3d.com/Packages/com.unity.purchasing@4.10/manual/Testing.html)).
* Download the app from Google Play through the internal testing link:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_21_f41d2c851f.png?updated_at=2023-12-28T16:06:28.194Z" alt="Internal testing link" />
</div>

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and Unity In-App Purchasing service. Always remember to test every feature before deploying to guarantee a flawless player experience.

For a deeper understanding of the underlying processes, check out the [tutorial video](https://youtu.be/8Pw4VUyWVY8).

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/iap-unity-sample/issues).

If you have questions, or comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)

{/* Finish with a video. This also appears in the Sidebar via the "tocVideo" metadata */}


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Mobile In-App Purchases (IAP) in Unity

### Overview

*Disclaimer: Openfort is not responible of such integration to be approved by Apple and/or Google*

This sample project showcases the Openfort advanced & compliant integration with [In-App Purchasing](https://docs.unity3d.com/Packages/com.unity.purchasing@4.10/manual/Overview.html) in Unity. The objective of this integration sample is to implement and showcase a **crypto In-App Purchasing system** compliant with the [rules/guidelines]() companies like Apple have set for this type of purchases in mobile apps.

<VideoSnippet title="Video" src="37yAu7YQXhg" />

### Specifications

The sample includes:

* [**`ugs-backend`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

  A .NET Core project with [Cloud Code C# modules](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules#Cloud_Code_C#_modules) that implement [Openfort C# SDK](https://www.nuget.org/packages/Openfort.SDK/1.0.21) methods. Needs to be hosted in Unity Gaming Services.

* [**`unity-client`**](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

  A Unity sample game that connects to `ugs-backend` through [Cloud Code](https://docs.unity.com/ugs/manual/cloud-code/manual). It uses [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) to have full compatibility with `ugs-backend` responses.

### Application Workflow

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample_workflow_d04f0d70f6.png?updated_at=2024-02-14T17:24:18.292Z" alt="Openfort In-App Purchase Advanced Sample workflow" />
</div>

### Prerequisites

* **Get started with Openfort**

  * [Sign in](https://dashboard.openfort.io/login) or [sign up](https://dashboard.openfort.io/register) and create a new dashboard project

* **Get started with UGS**

  * [Complete basic prerequisites](https://docs.unity.com/ugs/manual/overview/manual/getting-started#Prerequisites)
  * [Create a project](https://docs.unity.com/ugs/manual/overview/manual/getting-started#CreateProject)

* **Get started with Google Play Console**

  * [Create and set up your app](https://support.google.com/googleplay/android-developer/answer/9859152?hl=en)

* **Get started with Apple Developer Account**
  * [Set up everything needed for Apple development](https://developer.apple.com/help/account/)
  * Make sure to [sign the Paid Apps agreement](https://developer.apple.com/help/app-store-connect/manage-agreements/sign-and-update-agreements) and fill tax and banking details as it's needed for testing IAP.

### Setup Openfort dashboard

* [Add an NFT contract](https://dashboard.openfort.io/contracts/new)

  This sample requires an NFT contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (contract deployed in 80002 Amoy). You can use it for this tutorial too:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_4_9397f3633b.png?updated_at=2023-12-14T15:59:33.808Z" alt="Contract Info" />
  </div>

* [Add an ERC20 contract](https://dashboard.openfort.io/contracts/new)

  This sample also requires an ERC20 contract to run. You can [deploy a standard one](https://thirdweb.com/thirdweb.eth/TokenERC20) and then add it to the Openfort dashboard following the same logic as above.

* [Add a Policy](https://dashboard.openfort.io/policies/new)

  We aim to cover gas fees for our users when they mint the NFT. Set a new gas policy for that:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_5_ab3d8ad48d.png?updated_at=2023-12-14T15:59:33.985Z" alt="Gas Policy" />
  </div>

  Add a rule so the NFT contract uses this policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="NFT Policy Rule" />
  </div>

  Add also a rule for the ERC20 contract:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_22_aec7863428.png?updated_at=2023-12-31T16:02:32.817Z" alt="ERC20 Policy Rule" />
  </div>

* [Create two backend wallets](https://dashboard.openfort.io/accounts)

  {" "}

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_23_74b85444b2.png?updated_at=2023-12-31T16:09:09.921Z" alt="Backend wallet" />
  </div>

  1. Enter a name (treasure account) and click ***Add account***. This will automatically create a custodial wallet that we'll use to transfer the ERC20 tokens to the players. **IMPORTANT: Transfer a good amount of tokens from the created ERC20 contract to this wallet to facilitate testing**.
  2. Enter a name (minting account) and click ***Add account***. This will automatically create a custodial wallet that the players will transfer the NFTs to when they choose the sell them. They'll get rewarded from the Treasury Dev Account afterwards.

### Set up [`ugs-backend`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/ugs-backend)

* #### Set Openfort dashboard variables

  Open the [solution](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules.sln) with your preferred IDE, open [`SingletonModule.cs`](https://github.com/openfort-xyz/iap-unity-sample/blob/main/ugs-backend/CloudCodeModules/SingletonModule.cs) and fill in these variables:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample1_9ab5bedd91.png?updated_at=2024-02-13T23:41:17.097Z" alt="Singleton Module" />
  </div>

  * `OfApiKey`: [Retrieve the **Openfort secret key**](https://dashboard.openfort.io/developers/configuration/api-keys)
  * `OfNftContract`: [Retrieve the **NFT contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfGoldContract`: [Retrieve the **ERC20 contract API ID**](https://dashboard.openfort.io/contracts)
  * `OfSponsorPolicy`: [Retrieve the **Policy API ID**](https://dashboard.openfort.io/policies)
  * `OfDevTreasuryAccount`: [Retrieve the **Treasury Developer Account API ID**](https://dashboard.openfort.io/accounts)
  * `OfDevMintingAccount`: [Retrieve the **Minting Developer Account API ID**](https://dashboard.openfort.io/accounts)

* #### Package Code

  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Package_code).

* #### Deploy to UGS

  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Deploy_a_module_project).

* #### Add a currency to UGS project

  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/economy/manual/add-currency) to add a currency to your game:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample2_7de4fc0554.png?updated_at=2024-02-13T23:51:37.496Z" alt="UGS currency" />
  </div>

### Set up [`unity-client`](https://github.com/openfort-xyz/iap-unity-sample/tree/main/unity-client)

In Unity go to *Edit --> Project Settings --> Services* and link the `unity-client` to your UGS Project:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_16_c1ac7c4b45.png?updated_at=2023-12-28T15:52:03.478Z" alt="Services settings" />
</div>

Select your *Environment*:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_17_e60d56f379.png?updated_at=2023-12-28T15:52:03.577Z" alt="UGS environment" />
</div>

Now make sure *In-App Purchasing* is enabled and *Current Targeted Store* is set to ***Google Play***. Then follow the instructions to set the **Google Play License Key** to your UGS project:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_18_3c78605c09.png?updated_at=2023-12-28T15:52:03.586Z" alt="Google Play License Key" />
</div>

Your UGS project dashboard should look like this:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_19_6802cc268e.png?updated_at=2023-12-28T15:52:04.490Z" alt="License key in UGS dashboard" />
</div>

**Apple AppStore** doesn't need this *license key configuration* so if you're targeting **iOS** you're good to go.

### Android deployment

* #### Build App Bundle

  In Unity go to [*Android Player settings*](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html) and make sure *Other Settings* looks like this:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_7_e6ec7eb903.png?updated_at=2023-12-28T07:47:59.386Z" alt="Android Player settings" />
  </div>

  Also, make sure to sign the application with a [Keystore](https://docs.unity3d.com/Manual/android-keystore-create.html) in *Publishing Settings*:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_8_ecae38df0e.png?updated_at=2023-12-28T07:47:59.307Z" alt="Application Signing" />
  </div>

  Then go to *Build Settings*, check ***Build App Bundle (Google Play)*** and choose ***Build***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_9_6d1e1a5636.png?updated_at=2023-12-28T07:52:15.586Z" alt="Build" />
  </div>

* #### Set up Google Play Console

  * ##### Create internal release

    On your [Google Play Console](https://play.google.com/console/u/0/developers/7556582789169418933?onboardingflow=signup) app, go to *Release --> Testing --> Internal testing --> Testers* and select or create an email list with the emails that will test your app. Then choose ***Create new release***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_10_f700f82ef1.png?updated_at=2023-12-28T15:07:32.491Z" alt="New release" />
    </div>

    Upload the `.aab` file and then choose ***Next***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_11_06459575df.png?updated_at=2023-12-28T15:07:33.382Z" alt="Upload build" />
    </div>

    If needed, solve pending errors and warnings and then choose ***Save and publish***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_12_da52624cb6.png?updated_at=2023-12-28T15:07:32.481Z" alt="Save and publish" />
    </div>

  * ##### Import IAP catalog

    On your [Google Play Console](https://play.google.com/console/u/0/developers/7556582789169418933?onboardingflow=signup) app, go to *Monetize --> Products --> In-app products* and choose ***Import***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_13_04a57f78c6.png?updated_at=2023-12-28T15:07:32.484Z" alt="Create product" />
    </div>

    Upload the [`GooglePlayProductCatalog.csv`](https://github.com/openfort-xyz/iap-unity-sample/blob/main/unity-client/Assets/GooglePlayProductCatalog.csv) file (which contains all the in-app products) and choose ***Import***:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_14_9a114af583.png?updated_at=2023-12-28T15:07:32.397Z" alt="Import products" />
    </div>

    You should see all the products have been created:

    <div align="center">
      <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_15_45877d642d.png?updated_at=2023-12-28T15:07:32.278Z" alt="Products created" />
    </div>

* #### Testing

  Once the internal testing release is published, you have two options to test:

  * Build and run the .apk directly to your device ([if the *version number* is the same as in the internal release](https://docs.unity3d.com/Packages/com.unity.purchasing@4.10/manual/Testing.html)).
  * Download the app from Google Play through the internal testing link:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/iap_sample_21_f41d2c851f.png?updated_at=2023-12-28T16:06:28.194Z" alt="Internal testing link" />
  </div>

### iOS deployment

* #### Xcode: Build & Archive & Upload

  In Unity go to *File --> Build Settings* and choose ***Build And Run***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample3_40c42ce5e4.png?updated_at=2024-02-14T00:26:54.820Z" alt="Build to Xcode" />
  </div>

  This will automatically open Xcode. If you encounter a `signing error`, select your development team and enable ***Automatically manage signing***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample4_9e12130585.png?updated_at=2024-02-14T00:34:32.096Z" alt="Build to Xcode: error" />
  </div>

  Start the building process again **(cmd + B)** and when completed, go to ***Product --> Archive***:

  {" "}

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample5_f10cfb74a1.png?updated_at=2024-02-14T00:41:32.549Z" alt="Build to Xcode: archive" />
  </div>

  After completing, choose ***Distribute App***:

  {" "}

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample6_85f8e46b54.png?updated_at=2024-02-14T00:47:23.087Z" alt="Build to Xcode: Distribute app" />
  </div>

  Select ***TestFlight & App Store*** to enable both internal and external testing and choose ***Distribute***:

  {" "}

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample7_7b3068a974.png?updated_at=2024-02-14T01:15:28.984Z" alt="Build to Xcode: distribute" />
  </div>

  The app will be uploaded to **App Store Connect**:

  {" "}

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample8_f5a647899b.png?updated_at=2024-02-14T01:15:28.680Z" alt="Build to Xcode: complete" />
  </div>

* #### Set up App Store Connect app

  Go to [App Store Connect Apps](https://appstoreconnect.apple.com/apps), choose your newly uploaded app and under **Distribution --> In-App Purchases** add the purchases:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample9_8bfb82b934.png?updated_at=2024-02-14T01:15:30.097Z" alt="Build to Xcode: in-app purchases" />
  </div>

  Remember to fill the same *Product ID* as you have set in your **Unity IAP Catalog**. Do it for all your products:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample10_bace0d3453.png?updated_at=2024-02-14T01:15:29.278Z" alt="Build to Xcode: catalog" />
  </div>

  Go to the *TestFlight section* and choose ***Manage Missing Compliance*** for your build:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample11_c1f23d62a9.png?updated_at=2024-02-14T01:15:29.089Z" alt="Build to Xcode: catalog" />
  </div>

* #### Testing

  Go to *Internal Testers* ([add testers](https://developer.apple.com/help/app-store-connect/test-a-beta-version/add-testers-to-builds/)) and you should see your build ready to be tested:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_iap_advanced_sample12_2db9d9b6f4.png?updated_at=2024-02-14T01:15:29.491Z" alt="Build to Xcode: testers" />
  </div>

  Open the TestFlight in the iOS device where your tester Apple ID is configured and test the app!

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and Unity In-App Purchasing service. Always remember to test every feature before deploying to guarantee a flawless player experience.

For a deeper understanding of the underlying processes, check out the [tutorial video](https://www.youtube.com/watch?v=37yAu7YQXhg).

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/samples/issues).

If you have questions, or comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


## Add reCAPTCHA in your Unity game

### Overview

This is a sample project to showcase the Openfort integration with [Google reCAPTCHA V3](https://developers.google.com/recaptcha/docs/v3), a system to help you protect your sites from fraudulent activities, spam, and abuse. In this sample, we will activate reCAPTCHA verification every time the user tries to perform a key action like authenticating or minting an NFT.

The sample includes:

* [**`ugs-backend`**](https://github.com/openfort-xyz/unity-recaptcha-sample/tree/main/ugs-backend)

  Some [Cloud Code JS scripts](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/scripts) to interact with the Openfort API from UGS BaaS.

* [**`unity-client`**](https://github.com/openfort-xyz/unity-recaptcha-sample/tree/main/unity-client)

  A Unity sample game that connects to `ugs-backend` through [Cloud Code Client SDK](https://docs.unity.com/ugs/manual/cloud-code/manual). It uses [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) to have full compatibility with `ugs-backend` responses.

### Workflow diagram

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample_workflow_9d3da01894.png" alt="Openfort Unity reCAPTCHA V3 Sample Workflow" />
</div>

### Prerequisites

* **Get started with Openfort**
  * [Sign in](https://dashboard.openfort.io/login) or [sign up](https://dashboard.openfort.io/register) and create a new dashboard project

* **Get started with UGS**
  * [Complete basic prerequisites](https://docs.unity.com/ugs/manual/overview/manual/getting-started#Prerequisites)
  * [Create a project](https://docs.unity.com/ugs/manual/overview/manual/getting-started#CreateProject)

* **Get started with GitHub Pages**
  * [Create a repository for your site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-a-repository-for-your-site)
  * [Create your site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site)

### Setup Openfort dashboard

* [Add a Contract](https://dashboard.openfort.io/contracts/new)

  This sample requires an NFT contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (NFT contract deployed in 80002 Amoy). You can use it for this tutorial:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_4_9397f3633b.png?updated_at=2023-12-14T15:59:33.808Z" alt="Contract Info" />
  </div>

* [Add a Policy](https://dashboard.openfort.io/policies/new)

  We aim to cover gas fees for users. Set a new gas policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_5_ab3d8ad48d.png?updated_at=2023-12-14T15:59:33.985Z" alt="Gas Policy" />
  </div>

  Now, add a rule so our contract uses this policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="Policy Rule" />
  </div>

### Set up reCAPTCHA V3

Go to [reCAPTCHA v3 Admin Console](https://www.google.com/recaptcha/admin) to register a new site. Choose ***Switch to create a classic key*** if the option is available:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample1_011de519f7.png?updated_at=2024-02-02T14:36:18.691Z" alt="Set up reCAPTCHA V3: Switch to create a classic key" />
</div>

Enter a ***Label*** name, select the ***reCAPTCHA type*** and enter your GitHub Pages URL as a ***Domain***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample2_536c95791f.png?updated_at=2024-02-02T14:36:19.493Z" alt="Set up reCAPTCHA V3: Fill options" />
</div>

Accept the terms of service and choose ***Submit***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample3_12771b8ee4.png?updated_at=2024-02-02T14:36:19.586Z" alt="Set up reCAPTCHA V3: Submit" />
</div>

Copy the ***Site Key*** and the ***Secret Key*** and save them somewhere safe:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample4_01a863dd6e.png?updated_at=2024-02-02T14:36:21.176Z" alt="Set up reCAPTCHA V3: Copy keys" />
</div>

### Set up [`ugs-backend`](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/ugs-backend)

* #### Fill in environment variables

  * [Retrieve the **API Secret key**](https://dashboard.openfort.io/developers/configuration/api-keys) and fill in the [`openfortApiKey`](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/55f91101ff4eae301b6d8c98458023c6b3b34d6e/ugs-backend/CreateOpenfortPlayer.js#L5) variable.
  * [Use the same **API Secret key**](https://dashboard.openfort.io/developers/configuration/api-keys) to fill the [`openfortApiKey`](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/55f91101ff4eae301b6d8c98458023c6b3b34d6e/ugs-backend/MintNft.js#L5) variable.
  * [Retrieve the **NFT Contract API ID**](https://dashboard.openfort.io/contracts) and fill in the [`nftContractId`](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/55f91101ff4eae301b6d8c98458023c6b3b34d6e/ugs-backend/MintNft.js#L9C11-L9C25) variable.
  * [Retrieve the **Policy API ID**](https://dashboard.openfort.io/policies) and fill in the [`policyId`](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/55f91101ff4eae301b6d8c98458023c6b3b34d6e/ugs-backend/MintNft.js#L10C11-L10C19) variable.
  * Fill in the [`secretKey`](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/55f91101ff4eae301b6d8c98458023c6b3b34d6e/ugs-backend/VerifyReCaptcha.js#L6) with your **reCAPTCHA secret key**.

* #### Deploy to UGS
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/scripts/getting-started#Deploy_a_Cloud_Code_script) to deploy each and all of the Cloud Code scripts.

### Set up [`unity-client`](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/unity-client)

* #### Link to UGS project
  Follow the [official documentation steps](https://docs.unity.com/ugs/manual/kit/manual/get-started#Link_your_project) to link the `unity-client` to your UGS Project.

* #### Fill in needed variables

  On the [Main scene](https://github.com/openfort-xyz/unity-recaptcha-sample/tree/main/unity-client/Assets/Scenes), select the *ReCaptchaController* game object and fill in your **reCAPTCHA site key**:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample5_ad65b1ce5b.png?updated_at=2024-02-02T14:36:19.490Z" alt="Set up Unity client: Fill in reCAPTCHA site key" />
  </div>

### Build to WebGL

> **IMPORTANT:** You need to build this sample to the root folder of the GitHub Pages repository.

In Unity go to *File --> Build Settings*, select *Web* platform and choose ***Build***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample6_d388084266.png?updated_at=2024-02-02T14:36:16.787Z" alt="Build to WebGL" />
</div>

Find your GitHub Pages repository root folder and choose ***Select Folder***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample7_735cd4abc0.png?updated_at=2024-02-02T14:36:15.587Z" alt="Build to WebGL: Select folder" />
</div>

After the build is completed, go to your GitHub Pages repository URL and you should see the *Sign in* panel:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample8_c283fc6617.png?updated_at=2024-02-02T14:36:19.482Z" alt="Build to WebGL: Sign in panel" />
</div>

Open the browser console to check that reCAPTCHA V3 is loaded and ready:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample9_f55bb4e5a2.png?updated_at=2024-02-02T14:36:21.283Z" alt="Build to WebGL: reCAPTCHA ready" />
</div>

Click the ***Sign in*** button and after some authentication-related logs, the *Mint* panel should appear. In the console logs, we should see a positive reCAPTCHA verification score. Because we passed the reCAPTCHA verification, an Openfort player should have been created:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample10_97c88ae6ee.png?updated_at=2024-02-02T14:36:21.617Z" alt="Build to WebGL: positive score" />
</div>

If you click the ***Mint*** button, the game will go through another reCAPTCHA verification. After a brief period, you should see the *NFT minted* panel with the Openfort player account address in a button:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/unity_recaptcha_sample11_86ae061a30.png?updated_at=2024-02-05T11:21:12.597Z" alt="Build to WebGL: NFT minted" />
</div>

Click on the ***Address*** button to open Etherscan and see that the transaction is confirmed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_8_6b345bd148.png?updated_at=2023-12-14T16:05:00.991Z" alt="Etherscan" />
</div>

### Code walkthrough

All this is thanks to the [**`ReCaptcha.jslib plugin`**](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/main/unity-client/Assets/Plugins/WebGL/ReCaptcha.jslib) located in the Unity client, which allows the execution of reCAPTCHA V3 from the client. The `.jslib` methods are called from the [**`ReCaptchaController.cs`**](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/main/unity-client/Assets/Scripts/ReCaptchaController.cs).

Then, when reCAPTCHA V3 gets the response token from the execution, we validate it in the backend through [**`VerifyReCaptcha.js`**](https://github.com/openfort-xyz/unity-recaptcha-sample/blob/main/ugs-backend/VerifyReCaptcha.js)

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and Google reCAPTCHA V3. Always remember to test every feature before deploying to guarantee a flawless player experience.

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/unity-recaptcha-sample/issues).

If you have questions, or comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


## Use token bound accounts (ERC6551)

In this guide you'll find how to implement a token bound account based on a game character. This guide implements the backend code necessary to use token bound accounts in your game. It uses the [Openfort Node SDK](https://www.npmjs.com/package/@openfort/openfort-node). Architecture of the solution proposed in this guide:

<div align="center">
  <img alt="using-token-bound-accounts" src="https://blog-cms.openfort.io/uploads/Group_349_48e9e86864.svg" width="100%" height="100%" />
</div>

:::tip
For a genereral overview of token bound accounts, see the [Token Bound Accounts](https://www.openfort.io/blog/technical-dive-combining-token-bound-account-tba-with-account-abstraction-aa) blog post.
You can find the complete code of this guide in the [openfort samples GitHub](https://github.com/openfort-xyz/samples/tree/main/ERC6551-token-bound-accounts).
:::

### Prerequisites

When interacting with smart wallets through Openfort, import the contract and create a policy to sponsor gas. Get your secret key from the [Openfort dashboard](https://dashboard.openfort.io/developers/configuration/api-keys).

:::steps
#### 1. Import the NFT contract

Token bound accounts are based on the ownership of a non-fungible token. In this guide, we'll use a contract, deployed at in [Polygon Amoy](https://mumbai.polygonscan.com/) at [0x380...AC0](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1).

##### Dashboard

Add a new contract by clicking the `Add contract` button in the [Asset contracts](https://dashboard.openfort.io/contracts) section, then enter:

* The name of the contract (it can be any name you want; the name is only for identification purposes)
* The network (`chainId`) where the smart contract is located: 80002.
* The address of the contract.
* Because the contract is verified in the block explorer, there's no need to provide an ABI manually.

<div align="center">
  <img alt="DashboardAddContract" src="https://blog-cms.openfort.io/uploads/adding_contract_dashboard_09dce2f83c.png" width="60%" height="60%" />
</div>

##### API Methods

##### curl

```bash command-line
curl https://api.openfort.io/v1/contracts \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d name="SimpleNFT" \
    -d address="0xbed6a05ce8719bc00db1cc81a814192c82be1bb1" \
    -d chainId="80002"
```

##### Node.js

```ts server.ts
const openfort = new Openfort(process.env.YOUR_SECRET_KEY);
const SimpleNFT = await openfort.contracts.create({
    name: "SimpleNFT",
    address: "0xbed6a05ce8719bc00db1cc81a814192c82be1bb1",
    chainId: chainId,
});
```

#### 2. Set up gas sponsoring

##### Dashboard

Add a new policy by clicking the `Add policy` button in the [Policies page](https://dashboard.openfort.io/policies), then enter:

* The name of the policy (it can be any name you want; the name is only for identification purposes)
* The network (`chainId`) where the smart contract is located: 80002.
* As a fee sponsorship strategy, leave `pay gas for user`.
* Under policy rules, create two rules:
  * 1st rule:
    * Leave `contract_functions` under Rule model.
    * Under Contract, select the contract you imported in the previous step.
    * Under Function name, select `All functions`.
  * 2nd rule:
    * Choose `account_functions` under Rule model.

<div align="center">
  <img alt="GasPolicy" src="https://blog-cms.openfort.io/uploads/create_sponsor_7a1583a724.png" width="50%" height="50%" />
</div>
:::

##### API Methods

##### curl

```bash command-line
curl https://api.openfort.io/v1/policies \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d name="Trial sponsor" \
    -d chainId="80002" \
    -d "strategy[sponsorSchema]=pay_for_user"
```

Use the policy id to create policy rules and use the previously imported contract.

```bash command-line
curl https://api.openfort.io/v1/policies/:id/policy_rules \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d type="contract_functions" \
    -d functionName="All functions" \
    -d contract="con_..."
```

```bash command-line
curl https://api.openfort.io/v1/policies/:id/policy_rules \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d type="account_functions"
```

##### Node.js

```ts server.ts
const policy = await openfort.policies.create({
    name: "test",
    chainId: 80002,
    strategy: {
        sponsorSchema: SponsorSchema.PayForUser,
    },
});

await openfort.policyRules.create({
    contract: SimpleNFT.id,
    type: PolicySchema.ContractFunctions,
    policy: policy.id,
    functionName: "All functions",
});

await openfort.policyRules.create({
    type: PolicySchema.AccountFunctions,
    policy: policy.id,
});
```

### Create the character NFT

As you know, to create a token bound account, you need to first know what NFT will be used to define the ownership of the account.
Because in this guide we start from scratch, we'll also mint that NFT, but you could potentially use any NFT that you already own. If you want to use your own NFT, skip to the next section.

We'll use a regular Openfort account to mint it. We start by creating an Openfort player and a regular Openfort account.

```ts server.ts
const upgradeable_account = await openfort.accounts.create({
  chainId: chainId,
});
const player_upgradeable = upgradeable_account.player.id;
```

Then, we define the mint function interaction and create a `transactionIntent` using the gas sponsoring `policy` we created in the previous step.

```ts server.ts
const interactionsMintOwnerNFT: Interaction[] = [
  {
    contract: SimpleNFT.id,
    functionName: 'mint',
    functionArgs: [player_upgradeable.id],
  },
]
const transactionIntentSimpleNFT = await openfort.transactionIntents.create({
  player: player_upgradeable.id,
  interactions: interactionsMintOwnerNFT,
  policy: policy.id,
  chainId: chainId,
  optimistic: false,
})
```

And we're all set! The character NFT is minted and owned by the `player_upgradeable`'s account.

### Create a token bound account

Now that we have the NFT that will defined the ownership of the account, we can create a token bound account. Note that when creating the token bound account, we need to specify:

* The `externalOwnerAddress` field: the address that currently owns the character NFT.
* The `tokenContract` field: the address of the NFT contract.
* The `tokenId` field: the token id of the character NFT.
* The `accountType` field: specified that the account to be created is a token bound account.

We start off by creating a new player and then assign a new counterfactual token bound account to it:

```ts server.ts
const player_6551 = await openfort.players.create({
  name: '6551 account',
})
const account = await openfort.accounts.create({
  player: player_6551.id,
  chainId: chainId,
  accountType: DataAccountTypes.Erc6551,
  tokenContract: SimpleNFT.id,
  tokenId: simpleOwnerNFTTokenId,
  externalOwnerAddress: upgradeable_account.address,
})
```

### Transferring the character NFT

You can send the character NFT to another account by calling the `safeTransferFrom` function of the NFT contract.
This function takes the address of the current owner, the address of the new owner, and the token id as arguments.

In this case, we'll transfer the character NFT to the previously `account` ownerAddress. This is because Openfort accounts come, by default, with a managed signer.
Sending the NFT to the account ownerAddress allows a regular EOA to control the account.

```ts server.ts
const interactionsExecCall: Interaction[] = [
  {
    contract: SimpleNFT.id,
    functionName: 'approve',
    functionArgs: [ownerAddress, simpleOwnerNFTTokenId],
  },
  {
    contract: SimpleNFT.id,
    functionName: 'safeTransferFrom',
    functionArgs: [
      player_upgradeable.id,
      account.ownerAddress,
      simpleOwnerNFTTokenId,
    ],
  },
]
const transactionIntentTransferOwnerNFT =
  await openfort.transactionIntents.create({
    player: player_upgradeable.id,
    interactions: interactionsExecCall,
    policy: policy.id,
    chainId: chainId,
    optimistic: false,
  })
```

### Minting an asset into the character NFT

You can easily mint assets into the token bound account and even use it to mint assets.
Here we interact with the same simple NFT contract to mint an NFT into the token bound account.

```ts server.ts
const interactionsMintNFT: Interaction[] = [
  {
    contract: SimpleNFT.id,
    functionName: 'mint',
    functionArgs: [player_6551.id],
  },
]
const transactionIntentSimpleNFT6551 = await openfort.transactionIntents.create(
  {
    player: player_6551.id,
    interactions: interactionsMintNFT,
    policy: policy.id,
    chainId: chainId,
    optimistic: false,
  }
)
```


## Create and recover wallets in Unity

### Understanding embedded wallets

To create wallets for your users during the login flow, you need to configure the private key generation. The configuration depends on your chosen recovery method, so it's important to decide on your recovery strategy first.

**Make sure to wait for the embedded state ready before using the embedded wallet. Learn more about [how to check the embedded state](/docs/products/embedded-wallet/javascript/use-openfort#waiting-for-ready).**

### Decide a recovery method

Recovering the embedded wallet is needed when a user logs into a new device or when the private key is lost.

Openfort embedded wallets have two core recovery modes: automatic recovery and user-based recovery. At a high-level, this setting modulates how the embedded wallet's recovery share is encrypted and stored.

* **[Automatic recovery](/docs/products/embedded-wallet/javascript/signer/recovery#automatic-recovery)**: The recovery share is encrypted with a combination of project entropy and Openfort's entropy. When logging into a new device, users can immediately access their embedded wallet.

  <div>
    **Shield configuration**: Before configuring the automatic recovery,
    generate your project's **publishable and secret shield keys** and store the
    **encryption share**. Learn about the differrent API keys
    [here](/docs/configuration/api-keys#shield-secret-and-publishable-keys).
  </div>

* **[User-based recovery](/docs/products/embedded-wallet/javascript/signer/recovery#user-based-recovery):** The recovery share is encrypted by **user-provided entropy**. When logging into a new device, users must enter in their password to recover the embedded wallet on the new device. Once the private key has been recovered on a device, users will not need to enter their password on that devices again.

#### Automatic recovery

It is worth noting that while **automatic recovery** makes for smooth user UX (without needing to set up a recovery system upfront when logging in), it comes with tradeoffs. Notably, the root of trust with is in the user’s authentication token. This means access to the auth token grants access to the wallet. Accordingly, this token must be properly secured at all times.

When using automatic recovery, **Shield** generates a password that is used for the encryption of the recovery share. The full encryption key can only be accessed if the decryption request includes the user's auth token.

<div>
  **⚠️ Encryption share**: When using **automatic recovery**, its very important
  to ensure that the `encryption share` should not be available from the client
  side of the application.
</div>

**From your backend**, you should have an endpoint that generates an encryption session for the user. This endpoint should be protected and only accessible by the user who is requesting the encryption session (i.e. the user who is logging in).

<div>
  **Note**: An encryption session is requested every time
  `configureEmbeddedSigner` is called. The encryption session is only valid for
  **a single use**.
</div>

For example, in a Next.js API route, you can create an endpoint like this:

```ts protected-create-encryption-session.ts
import openfort from "./openfortAdminConfig";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const session = await openfort.registerRecoverySession(
    "YOUR_SHIELD_PUBLISHABLE_KEY",
    "YOUR_SHIELD_SECRET_KEY",
    "YOUR_SHIELD_ENCRYPTION_SHARE"
  );
  res.status(200).send({
    session: session,
  });
}
```

```ts openfortAdminConfig.ts
import Openfort from "@openfort/openfort-node";

const openfort = new Openfort("YOUR_OPENFORT_SECRET_KEY");

export default openfort;
```

Once we've secured the backend we setup the client side:

##### Openfort Auth

```csharp openfortManager.cs
using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.Networking;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
using static Clients.Shield;

public class EmbeddedSignerManager : MonoBehaviour
{
    private OpenfortSDK openfort;

    // Setup with Openfort authentication
    public async Task SetupAutomaticRecoveryWithOpenfort(string email, string password)
    {
        try
        {
            // Sign up the user
            AuthResponse response = await openfort.auth.signUpWithEmailPassword(email, password);
            string token = response.Token;

            // Get encryption session from your backend
            string encryptionSession = await GetEncryptionSession();

            // Configure the signer
            int chainId = 80002; // Polygon Amoy testnet
            ShieldAuthentication shieldAuthentication = new ShieldAuthentication(
                ShieldAuthType.Openfort,
                token
            )
            {
                EncryptionSession = encryptionSession
            };

            EmbeddedSignerRequest request = new EmbeddedSignerRequest({chainId, shieldAuthentication});
            await openfort.embeddedWallet.configure(request);

            Debug.Log("Automatic recovery setup complete");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error setting up automatic recovery: {e.Message}");
        }
    }
}
```

```csharp encryptionSession.cs
using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.Networking;

public class EncryptionSessionManager
{
    public static async Task<string> GetEncryptionSession()
    {
        string url = "https://your-api-endpoint.com/api/protected-create-encryption-session";

        using (UnityWebRequest webRequest = UnityWebRequest.Post(url, "{}"))
        {
            webRequest.SetRequestHeader("Content-Type", "application/json");

            var operation = webRequest.SendWebRequest();

            while (!operation.isDone)
                await Task.Yield();

            if (webRequest.result != UnityWebRequest.Result.Success)
            {
                Debug.LogError($"Failed to create encryption session: {webRequest.error}");
                throw new Exception("Failed to create encryption session");
            }

            string jsonResponse = webRequest.downloadHandler.text;
            SessionResponse response = JsonUtility.FromJson<SessionResponse>(jsonResponse);
            return response.session;
        }
    }
}

[Serializable]
public class SessionResponse
{
    public string session;
}
```

##### Third-party Auth

This example will showcase **Firebase** as the third-party auth provider. You can replace it with any other [third-party auth provider](#TODO).

```csharp openfortManager.cs
using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.Networking;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
using static Clients.Shield;

public async Task SetupAutomaticRecoveryWithThirdParty(string idToken)
    {
        try
        {
            // Authenticate with third-party provider
            await openfort.auth.authenticateWithThirdPartyProvider(
                new ThirdPartyProviderRequest(
                    ThirdPartyOAuthProvider.Firebase,
                    idToken,
                    TokenType.IdToken
                )
            );

            // Get encryption session from your backend
            string encryptionSession = await GetEncryptionSession();

            // Configure the signer
            int chainId = 80002;
            ShieldAuthentication shieldAuthentication = new ShieldAuthentication(
                ShieldAuthType.Openfort,
                idToken,
                "firebase",
                "idToken"
            )
            {
                EncryptionSession = encryptionSession
            };

            EmbeddedSignerRequest request = new EmbeddedSignerRequest({chainId, shieldAuthentication});
            await openfort.embeddedWallet.configure(request);

            Debug.Log("Third-party automatic recovery setup complete");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error setting up third-party automatic recovery: {e.Message}");
        }
    }
```

```csharp encryptionSession.cs
using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.Networking;

public class EncryptionSessionManager
{
    public static async Task<string> GetEncryptionSession()
    {
        string url = "https://your-api-endpoint.com/api/protected-create-encryption-session";

        using (UnityWebRequest webRequest = UnityWebRequest.Post(url, "{}"))
        {
            webRequest.SetRequestHeader("Content-Type", "application/json");

            var operation = webRequest.SendWebRequest();

            while (!operation.isDone)
                await Task.Yield();

            if (webRequest.result != UnityWebRequest.Result.Success)
            {
                Debug.LogError($"Failed to create encryption session: {webRequest.error}");
                throw new Exception("Failed to create encryption session");
            }

            string jsonResponse = webRequest.downloadHandler.text;
            SessionResponse response = JsonUtility.FromJson<SessionResponse>(jsonResponse);
            return response.session;
        }
    }
}

[Serializable]
public class SessionResponse
{
    public string session;
}
```

<div>
  **💡 Tip**: We recommend enabling user-based recovery for users. This is
  especially important to enforce as the value of assets in a user's wallet
  grows.
</div>

***

#### User-based recovery

**Password recovery**

Require that users set a password when the wallet is created, enforcing password-based recovery from the start.

If encrypted by user-provided entropy, **only the user can decrypt the recovery share**. Openfort never sees the user's password. Therefore, if you're not planning to ever user the automatic recovery mode, you can use the `encryption share` in the client side of the application.

##### Openfort Auth

```csharp
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
public class openfortManager: MonoBehaviour
{
    private OpenfortSDK Openfort;
    private async void AuthAndSetPassordRecoveryMethod(string email, string password, string recoveryPassword)
    {
        AuthResponse response = await openfort.auth.signUpWithEmailPassword(email, password);
        string token = response.Token;
        int chainId = 80002;
        ShieldAuthentication shieldAuthentication = new ShieldAuthentication(ShieldAuthType.Openfort, token);
        RecoveryParams recoveryParams = new RecoveryParams
        {
            password = recoveryPassword,
            recoveryMethod = RecoveryMethod.PASSWORD
        };
        EmbeddedSignerRequest request = new EmbeddedSignerRequest({chainId, shieldAuthentication, recoveryParams});
        await openfort.embeddedWallet.configure(request);
    }
}
```

##### Third-party Auth

This example will showcase **Firebase** as the third-party auth provider. You can replace it with any other third-party auth provider [supported by Openfort](#TODO) or with [Custom Auth](#TODO).

```csharp
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
public class openfortManager: MonoBehaviour
{
    private OpenfortSDK Openfort;
    private async void AuthAndSetPassordRecoveryMethod(string token, string recoveryPassword)
    {
        await openfort.auth.authenticateWithThirdPartyProvider(new ThirdPartyProviderRequest(ThirdPartyOAuthProvider.Firebase, token, TokenType.IdToken));
        int chainId = 80002;
        ShieldAuthentication shieldAuthentication = new ShieldAuthentication(ShieldAuthType.Openfort, token, "firebase", "idToken");
        RecoveryParams recoveryParams = new RecoveryParams
        {
            password = recoveryPassword,
            recoveryMethod = RecoveryMethod.PASSWORD
        };
        EmbeddedSignerRequest request = new EmbeddedSignerRequest({chainId, shieldAuthentication, recoveryParams});
        await openfort.embeddedWallet.configure(request);
    }
}
```

***

### Pregeneration

Openfort also allows you to pregenerate embedded wallets for your users, even before they first login to your game. Please see our [pregeneration guide](/docs/products/server/pregenerate-wallets) for more.


## Sign messages

### Prerequisites

Before implementing message signing:

* Ensure Openfort's `embeddedState` is `ready`
* Verify the user is properly authenticated
* Have an embedded wallet configured

### Message Signing

To request a signature from a user, use the `SignMessage` method. This implements the EIP-191 [personal\_sign](https://docs.metamask.io/wallet/reference/personal_sign/) standard.

```csharp
using UnityEngine;
using System;
using System.Threading.Tasks;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class MessageSigningManager : MonoBehaviour 
{
    private OpenfortSDK openfort;

    public async Task SignBasicMessage(string message)
    {
        try 
        {
            var signMessageRequest = new SignMessageRequest(message);
            var signature = await openfort.embeddedWallet.signMessage(signMessageRequest);
            Debug.Log($"Message signed successfully. Signature: {signature}");
            return signature;
        }
        catch (Exception e)
        {
            Debug.LogError($"Error signing message: {e.Message}");
            throw;
        }
    }
}
```

### Typed Data Signing

For signing EIP-712 typed data, use the `SignTypedData` method. This implements the [eth\_signTypedData\_v4](https://docs.metamask.io/wallet/reference/eth_signtypeddata_v4/) standard.

```csharp
public class MessageSigningManager : MonoBehaviour 
{
    // ... previous code ...

    public async Task SignTypedData(
        Dictionary<string, object> domain,
        Dictionary<string, object[]> types,
        Dictionary<string, object> value)
    {
        try 
        {
            var request = new SignTypedDataRequest(domain, types, value);
            var signature = await openfort.embeddedWallet.signTypedData(request);
            Debug.Log($"Typed data signed successfully. Signature: {signature}");
            return signature;
        }
        catch (Exception e)
        {
            Debug.LogError($"Error signing typed data: {e.Message}");
            throw;
        }
    }
}
```

#### Example of Typed Data Structure

```csharp
// Example of structured data for signing
public void CreateAndSignTypedData()
{
    var domain = new Dictionary<string, object>
    {
        { "name", "My Game" },
        { "version", "1" },
        { "chainId", 1 },
        { "verifyingContract", "0x1234567890123456789012345678901234567890" }
    };

    var types = new Dictionary<string, object[]>
    {
        { "Person", new[] 
            {
                new { name = "name", type = "string" },
                new { name = "score", type = "uint256" }
            }
        }
    };

    var value = new Dictionary<string, object>
    {
        { "name", "Alice" },
        { "score", 100 }
    };

    SignTypedData(domain, types, value);
}
```

### Examples

#### [Unity Sample Android Embedded Wallet](https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer)

An integration with Google Play Games using Firebase Auth as a third party auth provider to create a non-custodial embedded wallet.

#### [Unity Sample WebGL Embedded Wallet](https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer)

An integration with Openfort Auth with non-custodial embedded wallet.

export const examples = [
  {
    name: 'Unity Sample Android Embedded Wallet',
    description: 'An integration with Google Play Games using Firebase Auth as a third party auth provider to create a non-custodial embedded wallet.',
    href: 'https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer',
  },
  {
    name: 'Unity Sample WebGL Embedded Wallet',
    description: 'An integration with Openfort Auth with non-custodial embedded wallet.',
    href: 'https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer',
  }
]


## Manage embedded wallet state

There are **two** essential steps to configure Openfort's embedded wallets in your Unity application:

1. Configure the embedded wallet
2. Wait for the embedded wallet to be ready

### Embedded Wallet Configuration

The Openfort SDK provides methods to configure a non-custodial embedded wallet for blockchain interactions and transaction signing in your Unity game.

Here's how to implement the configuration:

```csharp
using UnityEngine;
using System;
using System.Threading.Tasks;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;

public class OpenfortManager : MonoBehaviour
{
    private OpenfortSDK openfort;

    private async void Start()
    {
        try
        {
            openfort = await OpenfortSDK.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
        }
        catch (Exception e)
        {
            Debug.LogError($"Initialization error: {e.Message}");
        }
    }

    public async Task ConfigureEmbeddedWallet(string authToken, string password = null)
    {
        try
        {
            int chainId = 80002; // Polygon Amoy testnet

            // Create shield authentication configuration
            var shieldAuthentication = new ShieldAuthentication(
                ShieldAuthType.Openfort, // or ShieldAuthType.Custom for third-party auth
                authToken
            );

            RecoveryParams recoveryParams = new RecoveryParams
            {
                password = password,
                recoveryMethod = RecoveryMethod.PASSWORD
            };

            // Create the embedded wallet request
            var request = new EmbeddedSignerRequest({
                chainId,
                shieldAuthentication,
                recoveryParams
            });

            // Configure the embedded wallet
            await openfort.embeddedWallet.configure(request);
            Debug.Log("Embedded signer configured successfully");
        }
        catch (Exception e)
        {
            Debug.LogError($"Configuration error: {e.Message}");
            throw;
        }
    }
}
```

#### Configuration Parameters

The `EmbeddedSignerRequest` takes the following parameters:

| Parameter  | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| chainId    | The blockchain network identifier. See [supported chains](/docs/configuration/chains) |
| shieldAuth | Authentication configuration including auth type and token                            |
| password   | Optional: Recovery password for user-based recovery                                   |

The `ShieldAuthentication` configuration includes:

| Parameter | Description                                                 |
| --------- | ----------------------------------------------------------- |
| auth      | Either `ShieldAuthType.Openfort` or `ShieldAuthType.Custom` |
| token     | The access or ID token for user verification                |

### Checking Embedded wallet State

The embedded wallet goes through several states during initialization. It's crucial to wait for the proper state before using the signer.

#### Embedded States

| State                             | Value | Description                      |
| --------------------------------- | ----- | -------------------------------- |
| NONE                              | 0     | Initial SDK state                |
| UNAUTHENTICATED                   | 1     | Before user authentication       |
| EMBEDDED\_SIGNER\_NOT\_CONFIGURED | 2     | Before wallet configuration      |
| CREATING\_ACCOUNT                 | 3     | Creating new account for chainID |
| READY                             | 4     | Wallet ready for use             |

Here's how to check the embedded wallet state:

```csharp
public class OpenfortManager : MonoBehaviour
{
    private OpenfortSDK openfort;

        public async UniTask<EmbeddedState> GetEmbeddedState()
    {
        return await GetOpenfortImpl().GetEmbeddedState();
    }
}
```


## Using smart wallets

Smart wallets in Openfort are your primary interface for blockchain interactions. Once an embedded wallet is set up, a smart wallet is automatically created and associated for your user.

:::info
There is no need to use the EIP1193 provider directly. Instead, use the Openfort SDK to interact with the smart wallet.
:::

### Getting an EIP-1193 provider

All of Openfort's wallets can export a standard [EIP-1193 provider](https://eips.ethereum.org/EIPS/eip-1193) object. This allows your app to request signatures and transactions from the wallet, using familiar JSON-RPC requests like `personal_sign` or `eth_sendTransaction`.

To get a wallet's EIP-1193 provider, use the openfort `getEthereumProvider` method:

```csharp
public class OpenfortManager : MonoBehaviour
{
    private OpenfortSDK openfort;

      public async UniTask<Provider> GetEthereumProvider(EthereumProviderRequest request)
      {
          return await GetOpenfortImpl().GetEthereumProvider(request);
      }
    }
```


## Using Smart Wallets

To use smart wallets, you could use the EIP1193 provider or use a backend. This guide teaches how to make different requests to the smart wallet with the backend and Unity (it's easier to do so in the context of gaming because no need to encode transactions with Unity).

### Sign message

To sign message with the smart wallet simply call the Openfort's `signMessage` or `signTypedData` method like so:

```csharp
SignMessageRequest signMessageRequest = new SignMessageRequest("Hello World!");
string signature = await openfort.embeddedWallet.signMessage(signMessageRequest);
```

### Transactions

#### 1. Create a transaction- <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span>

Create a request to your backend to create a transaction. In the body of the request:

* Include the `player` that signs the transaction.
* Include the `policy` that interacts with the contract for gas. If non-existent the user will need to have gas tokens.
* Include `optimistic` if you want the transactions to be confirmed faster.

Depending on the type of transaction you're creating you'll define `interactions`. The `interactions` field is an array of objects that contain the information of the contract to interact with, the function to call, and the arguments to pass to the function.

* the interactions field contains the `contract` that has previously been added to Openfort.
* the `functionName` defines the function to call from within the contract.
* If there exist more than one function with the same name, the `functionArgs` will be used to determine which function to call.

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player="pla_..." \
  -d policy="pol_..." \
  -d chainId=80002 \
  -d optimistic=true \
  -d "interactions[0][contract]"="con_..." \
  -d "interactions[0][functionName]"="mint" \
  -d "interactions[0][functionArgs][0]"="0x63B7...484f"
```

```ts [node]
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const playerId = "pla_...";
const contractId = "con_...";
const policyId = "pol_...";
const chainId = 80002;
const optimistic = false;

const interaction_mint = {
  contract: contractId,
  functionName: "mint",
  functionArgs: [playerId],
};

await openfort.transactionIntents.create({
    "player":playerId,
    "chainId":chainId,
    "optimistic":optimistic,
    "interactions":[interaction_mint],
    "policy":policyId
  });
```

```csharp [.net]
string policyId = "pol_...";
string contractId = "con_...";
string playerId = "pla_...";
int chainId = 80002;
bool optimistic = false;

var interactionMint = new Interaction
(
  contract: contractId,
  functionName: "mint",
  functionArgs: new List<object> { playerId }
);

var transactionIntentRequest = new CreateTransactionIntentRequest
    (
        player: playerId,
        chainId: chainId,
        policy: policyId,
        optimistic: optimistic,
        interactions: new List<Interaction> { interactionMint }
    );
await client.TransactionIntents.Create(transactionIntentRequest);
```
:::

##### Native

Send the value of native tokens in the smallest denomination of the native currency i.e. wei (10^18) and as a `string`.

:::tip
The `to` parameter accepts:

* any valid account `address` e.g. 0x680d2719F09B23F644c136Ab7336D42b6a76AdcC
* a player `id` e.g. pla\_...
* an account `id` e.g. acc\_...
:::

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player="pla_..." \
  -d policy="pol_..." \
  -d chainId=80002 \
  -d optimistic=true \
  -d "interactions[0][value]=1000" \
  -d "interactions[0][to]=pla_..."
```

```ts [nodeJS]
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const playerId = "pla_...";
const policyId = "pol_...";
const chainId = 80002;
const optimistic = false;

const interaction_transfer = {
  value: "100",
  to: playerId
};

await openfort.transactionIntents.create({
    "player":playerId,
    "chainId":chainId,
    "optimistic":optimistic,
    "interactions":[interaction_transfer],
    "policy":policyId
  });
```

```csharp [.net]
string policyId = "pol_...";
string playerId = "pla_...";
int chainId = 80002;
bool optimistic = false;

var interactionTransfer = new Interaction
(
  value: "100",
  to: playerId
);

var transactionIntentRequest = new CreateTransactionIntentRequest
    (
        player: playerId,
        chainId: chainId,
        policy: policyId,
        externalOwnerAddress: null,
        optimistic: optimistic,
        confirmationBlocks: 0,
        interactions: new List<Interaction> { interactionTransfer}
    );
await client.TransactionIntents.Create(transactionIntentRequest);
```
:::

:::info
The `policy` used to sponsor a transaction that sends native tokens should have the `account_functions` policy rule.
:::

For a useful resource for computing the Wei, you can visit the [wei calculator](https://eth-converter.com/).

##### Batch

Smart accounts support batching transactions, allowing multiple actions to be rolled into one. This feature significantly simplifies Web3 interactions for your users. For example, instead of executing `approve()` and then `transfer()`, your user can perform both in a single transaction.

Batching transactions offers several key benefits:

* Users only wait for one transaction to complete instead of multiple.
* Users save on gas fees.
* If any transaction in the batch fails, the entire batch reverts, preventing users from ending up in an inconsistent state. This characteristic is known as "atomicity."

Fore security reasons, there is a limit of 9 interactions per transaction intent.

:::tip
To execute a batch transaction, you can send a transaction intent with **multiple interactions**, and each interaction will be executed in the order they are received.
:::

:::note
Openfort systems check the contract's ABI to find a function signature based on the `functionName` that you provide and the number of `functionArgs`.
:::

In the case that, in your contract, you have multiple functions with the same `functionName` and number of arguments, you can also include the `functionName` together with the argument types e.g. mint(address)

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/transaction_intents \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player="pla_...", \
  -d policy="pol_..." \
  -d chainId=80002 \
  -d optimistic=true \
  -d "interactions[0][contract]=con_..." \
  -d "interactions[0][functionName]=mint" \
  -d "interactions[0][functionArgs][0]=0x63B7...484f" \
  -d "interactions[1][contract]=con_..." \
  -d "interactions[1][functionName]=transfer" \
  -d "interactions[1][functionArgs][0]=0x32B7...213d"
```

```ts [nodeJS]
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const playerId = "pla_...";
const contractId = "con_...";
const policyId = "pol_..."; 
const chainId = 80002;
const optimistic = false;

const interaction_mint = {
  contract: contractId,
  functionName: "mint",
  functionArgs: [playerId],
};
const interaction_transfer = {
  contract: contractId,
  functionName: "transfer",
  functionArgs: [playerId],
};

await openfort.transactionIntents.create({
    "player":playerId,
    "chainId":chainId,
    "optimistic":optimistic,
    "interactions":[interaction_mint, interaction_transfer],
    "policy":policyId
  });
```

```csharp [.net]
string policyId = "pol_...";
string contractId = "con_...";
string playerId = "pla_...";
int chainId = 80002;
bool optimistic = false;

var interactionMint = new Interaction
(
  contract: contractId,
  functionName: "mint",
  functionArgs: new List<object> { playerId }
);

var interactionTransfer = new Interaction
(
  contract: contractId,
  functionName: "transfer",
  functionArgs: new List<object> { playerId }
);

var transactionIntentRequest = new CreateTransactionIntentRequest
    (
        player: playerId,
        chainId: chainId,
        policy: policyId,
        externalOwnerAddress: null,
        optimistic: optimistic,
        confirmationBlocks: 0,
        interactions: new List<Interaction> { interactionMint, interactionTransfer}
    );
await client.TransactionIntents.Create(transactionIntentRequest);
```
:::

#### 2. Sign the transaction. - <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

Use the `nextAction` returned by the backend to sign the transaction with the embedded wallet.

The transaction will be automatically signed and broadcasted by using the `sendSignatureTransactionIntentRequest` method.

```csharp
private async void Mint() {
  // your backend that creates a mint request
  var webRequest = UnityWebRequest.Post("https://your-backend.com/api/mint", "");
  webRequest.SetRequestHeader("Authorization", "Bearer " + AccessToken);
  webRequest.SetRequestHeader("Content-Type", "application/json");
  webRequest.SetRequestHeader("Accept", "application/json");
  await SendWebRequestAsync(webRequest);

  Debug.Log("Mint request sent");
  if (webRequest.result != UnityWebRequest.Result.Success) {
    Debug.Log("Mint Failed: " + webRequest.error);
    return;
  }

  var responseText = webRequest.downloadHandler.text;
  Debug.Log("Mint Response: " + responseText);
  var responseJson = JsonConvert.DeserializeObject < RootObject > (responseText);
  var id = responseJson.Data.Id;
  if (responseJson.Data.NextAction == null) {
    Debug.Log("No Next Action");
    return;
  }

  var nextAction = responseJson.Data.NextAction.Payload.UserOpHash;

  Debug.Log("Next Action: " + nextAction);
  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  var intentResponse = await Openfort.SendSignatureTransactionIntentRequest(id, nextAction);
  Debug.Log("Intent Response: " + intentResponse);
}

private Task SendWebRequestAsync(UnityWebRequest webRequest) {
  TaskCompletionSource < bool > tcs = new TaskCompletionSource < bool > ();
  webRequest.SendWebRequest().completed += _ => {
    switch (webRequest.result) {
    case UnityWebRequest.Result.Success:
      tcs.SetResult(true);
      break;
    default:
      tcs.SetException(new Exception(webRequest.error));
      break;
    }
  };
  return tcs.Task;
}
```

### Examples

#### [Unity Sample Android](https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer)

An integration with Google Play Games using Firebase Auth as a third party auth provider to create a non-custodial embedded wallet.

#### [Unity Sample WebGL](https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer)

An integration with Openfort Auth with non-custodial embedded wallet.

export const examples = [
  {
    name: 'Unity Sample Android',
    description: 'An integration with Google Play Games using Firebase Auth as a third party auth provider to create a non-custodial embedded wallet.',
    href: 'https://github.com/openfort-xyz/sample-unity-firebaseauth-embedded-signer',
  },
  {
    name: 'Unity Sample WebGL',
    description: 'An integration with Openfort Auth with non-custodial embedded wallet.',
    href: 'https://github.com/openfort-xyz/sample-unity-webgl-embedded-signer',
  }
]


## Backend wallet with Rest API

You can also request Openfort's REST API directly to use backend wallets. When requesting the REST API directly, you must set certain headers on your requests.

:::steps
#### Get your API Keys

[Open your project](https://dashboard.openfort.io) in the Openfort Dashboard and grab your secret key from the [project settings](https://dashboard.openfort.io/developers/configuration/api-keys).

All API requests must be authenticated using your secret key. Include it in the Authorization header using Basic auth.

```bash Terminal
# Export your secret key as an environment variable
export YOUR_SECRET_KEY=sk_test_...

# Test the API connection
curl https://api.openfort.io/v1/tokens \
  -u "$YOUR_SECRET_KEY:"
```

#### Create a backend wallet

Backend wallet (`dac`) can be used for escrow, minting, and transferring assets. Create a new custodial Backend wallet using the API.

The response will include the backend wallet ID (starts with `dac_`) and its blockchain address.

```bash Terminal
curl https://api.openfort.io/v1/settings/developer_accounts \
  -u "$YOUR_SECRET_KEY:" \
  -d name="Transfer Account"
```

#### Add a contract to Openfort

Add your token contract to Openfort. This example uses a simple ERC-20 contract with transfer functionality.

Save the returned contract ID (starts with `con_`) for the next step.

```bash Terminal
curl https://api.openfort.io/v1/contracts \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d address="0x2522F4Fc9aF2E1954a3D13f7a5B2683A00a4543A" \
  -d abi=[
      {
        "inputs": [
          {
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "internalType": "uint256",
            "name": "amount",
            "type": "uint256"
          }
        ],
        "name": "transfer",
        "outputs": [
          {
            "internalType": "bool",
            "name": "",
            "type": "bool"
          }
        ],
        "stateMutability": "nonpayable",
        "type": "function"
      }
    ] \
  -d name="Example Token"
```

#### Create a Transfer Transaction

Create a transaction intent to transfer tokens using your backend wallet. Replace:

* `dac_...` with your Backend wallet ID
* `con_...` with your contract ID
* `pla_...` with the recipient's player ID
* The amount with your desired transfer amount in wei (the example shows 1 token with 18 decimals)

Setting `optimistic=true` means the response will be returned after simulation but before on-chain confirmation.

```bash Terminal
curl https://api.openfort.io/v1/transaction_intents \
  -u "$YOUR_SECRET_KEY:" \
  -d chainId=80002 \
  -d 'account=dac_...' \
  -d optimistic=true \
  -d 'interactions[0][contract]=con_....' \
  -d 'interactions[0][functionName]=transfer' \
  -d 'interactions[0][functionArgs][0]=pla_...' \
  -d 'interactions[0][functionArgs][1]=1000000000000000000'
```

#### Check Transaction Status

You can check the status of your transaction using the transaction intent ID returned in the previous step.

The response will include the transaction hash and status once the transaction is processed.

```bash Terminal
curl https://api.openfort.io/v1/transaction_intents/tin_... \
  -u "$YOUR_SECRET_KEY:"
```
:::


## Backend wallet with SDK (Node.js)

You can use backend wallets via Openfort's NodeJS Server SDK (or .net). Follow the instructions below to configure your desired integration.

::::steps
#### Set up Openfort Node.js SDK

[Open your project](https://dashboard.openfort.io) in the Openfort Dashboard.

The latest version of the Openfort Node.js server-side SDK supports Node.js versions 14+.

```bash Terminal
mkdir openfort-tutorial
cd openfort-tutorial
npm init -y
npm install @openfort/openfort-node --save
touch index.js
```

#### Declare Openfort Environment Variables

After your project is ready, grab your secret\_key from the [project settings](https://dashboard.openfort.io/developers/configuration/api-keys).

Create a `.env` file and populate it with your project's secret key.

:::code-group
```text .env
YOUR_SECRET_KEY=sk_test_...
```

```json package.json
{
  "name": "node",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "node index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@openfort/openfort-node": "^0.6.10"
  }
}
```
:::

#### Create a backend wallet

Backend wallet (`dac`) can be used for escrow, minting, and transferring assets. You can create a new custodial backend wallet or add your own external account by providing a signature and address.

```js index.js
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(process.env.YOUR_SECRET_KEY);

const main = async () => {
  // Create a new custodial backend wallet
  const developerAccount = await openfort.settings.createDeveloperAccount({
    name: "Minting Account"
  });
  
  console.log("Success! Here is your backend wallet id: " + developerAccount.id);
};

main().then(() => process.exit(0));
```

#### Add a contract to Openfort

We'll use a simple [ERC-721](https://eips.ethereum.org/EIPS/eip-721) contract on the [Polygon Amoy network](https://www.oklink.com/amoy/).

Once added, Openfort will return a contract id that starts with `con_`.

```bash Terminal
curl https://api.openfort.io/v1/contracts \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d chainId=80002 \
  -d address="0x2522F4Fc9aF2E1954a3D13f7a5B2683A00a4543A" \
  -d abi=[
      {
      "inputs": [
        {
          "internalType": "address",
          "name": "_to",
          "type": "address"
        }
      ],
      "name": "mint",
      "outputs": [],
      "stateMutability": "nonpayable",
      "type": "function"
      }
    ] \
  -d name="Simple NFT"
```

#### Mint an NFT using the backend wallet

Use your backend wallet to mint an NFT. The wallet will be used to pay for gas fees.

Make sure to replace the contract id with your own.

```js index.js
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(process.env.YOUR_SECRET_KEY);

const main = async () => {
  const developerAccount = await openfort.settings.createDeveloperAccount({
    name: "Minting Account"
  });
  
  const contractId = "con_...";
  const chainId = 80002;
  const optimistic = false;
  const tokenId = '1'; // Token ID to mint, should be unique
  
  const interaction_mint = {
    contract: contractId,
    functionName: "mint",
    functionArgs: [developerAccount.address, tokenId],
  };

  const transactionIntent = await openfort.transactionIntents.create({
    "account": developerAccount.id,
    "chainId": chainId,
    "optimistic": optimistic,
    "interactions": [interaction_mint]
  });
  
  console.log("Success! Here is your transactionIntent id: " + transactionIntent.id);
};

main().then(() => process.exit(0));
```

#### Run the script

You're all set! Run the development server on your Terminal.

You can check the transaction details in your [dashboard](https://dashboard.openfort.io/dashboard).

```bash Terminal
npm run dev
```
::::


## Linking & unlinking accounts

The user identity represents an authentication method associated to the user. For example, if a user signs in using their email, an email identity will be associated with the user.

Developers can use Openfort to prompt users to link additional accounts (such as a wallet or Discord profile) at any point in their user journey, not just during login.

### Linking accounts

#### Link email

Links an email and password to an existing account using an authentication token.

```tsx auth.tsx
import openfort from "./openfortConfig"

const email = 'EMAIL';
const password = 'PASSWORD';
const authToken = 'YOUR_USER_AUTH_TOKEN';

async function linkEmailPassword() {
  await openfort.auth.linkEmailPassword({email, password, authToken});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Link social accounts

Initializes an OAuth linking process.

```tsx auth.tsx
import openfort from "./openfortConfig"
const provider = 'OAuth provider';

async function initLinkOAuth() {
  await openfort.auth.initLinkOAuth({provider});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Link wallets

Links a wallet using SIWE.

```tsx auth.tsx
import openfort from "./openfortConfig"

const signature = 'SIWE signature';
const message = 'SIWE message';
const walletClientType = 'Wallet client type';
const connectorType = 'Connector type';
const authToken = 'YOUR_USER_AUTH_TOKEN';

async function linkWallet() {
  await openfort.auth.linkWallet({signature, message, walletClientType, connectorType, authToken});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Link third party providers

Links a third party provider to an existing account using an authentication token.

```tsx auth.tsx
import openfort from "./openfortConfig"
const provider = 'Third Party provider';
const token = 'Third Party token';
const tokenType = 'Type of the token (idToken or customToken)'

async function linkThirdParty() {
  await openfort.auth.linkThirdPartyProvider({provider, token, tokenType});
}
```

### Unlinking accounts

Once a user has linked additional accounts to their profile, you may also want to give them the option to unlink those accounts.

#### Unlink email

Unlinks an email and password from an existing account using an authentication token.

```tsx auth.tsx
import openfort from "./openfortConfig"
const email = 'EMAIL';

async function unlinkEmailPassword() {
  await openfort.auth.unlinkEmailPassword(email);
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Unlink social accounts

Unlinks an OAuth provider from the account.

```tsx auth.tsx
import openfort from "./openfortConfig"
const provider = 'OAuth provider';

async function unLinkOAuth() {
  await openfort.auth.unlinkOAuth({provider});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Unlink wallets

Unlinks a wallet.

```tsx auth.tsx
import openfort from "./openfortConfig"

const address = 'Wallet address';
const authToken = 'YOUR_USER_AUTH_TOKEN';

async function unlinkWallet() {
  await openfort.auth.unlinkWallet({provider, address});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```

#### Unlink third party provider

Unlinks a third party provider from an existing account using an authentication token.

```tsx auth.tsx
import openfort from "./openfortConfig"
const provider = 'Third Party provider';
const token = 'Third Party token';
const tokenType = 'Type of the token (idToken or customToken)'

async function unlinkThirdParty() {
  await openfort.unlinkThirdPartyProvider({provider, token, tokenType});
}
```

```ts openfortConfig.ts
import Openfort from '@openfort/openfort-js';

const openfort = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  }
});

export default openfort;
```


import { MultiOptionDisplay } from '@/components/MCP/MultiOptionDisplay';

## Using Session Keys

Session keys are programmable access tokens with specific permissions, designed for controlled interactions. Examples include:

* Granting access to specific areas or features.
* Limiting usage to a set amount of resources (e.g., 1000 units of currency).
* Time-bound validity (e.g., expiring after 3 days).

Permissions can be combined, enabling fine-tuned, context-specific capabilities.

:::tip
Check out our sample registering a session key with an account with a non-custodial signer: [GitHub source](https://github.com/openfort-xyz/openfort-js/tree/main/examples/apps/auth-sample).
:::

This section will guide you through the process of registering a session key and using it to mint an asset with a player's smart account. Choose your preferred implementation approach:

<MultiOptionDisplay
  options={[
  { id: 'web3-library', label: 'Web3 Library (EIP-1193)' },
  { id: 'openfort-sdk', label: 'Openfort SDK' },
]}
/>

<span id="web3-library" className="hidden [&>*]:mb-6!">
  ### Standard (EIP-1193 provider)

  Using [EIP-7715](https://github.com/pedrouid/ERCs/blob/19c16341c57f6ac8770cb778d60845dcf30f6a40/ERCS/erc-7715.md). The `request` method of the EIP-1193 provider can be used to request signatures. First, get the provider:

  :::code-group
  ```tsx [client.tsx]
  import openfort from "./openfortConfig"
  // This example assumes you have already checked that Openfort 'embeddedState' is 
  // `ready` and the user is `authenticated`
  const provider = openfort.embeddedWallet.getEthereumProvider();
  ```

  ```ts [openfortConfig.ts]
  import Openfort from '@openfort/openfort-js';

  const openfort = new Openfort({
    baseConfiguration: {
      publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
    },
    shieldConfiguration: {
      shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
    },
  });

  export default openfort;
  ```
  :::

  Smart wallets support sending a batch of transactions in a single, atomic submission to the network.

  To register a session key with a smart wallet, call the `wallet_grantPermissions` method.

  As an example, you might batch together a transaction to approve a USDC spender and to transfer USDC like so:

  ```tsx
  import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';

  const sessionKey = generatePrivateKey();
  const accountSession = privateKeyToAccount(sessionKey).address;

  await provider.request({
    method: 'wallet_grantPermissions',
    params: [
      {
        signer:{
          type: "account",
          data:{
            id: accountSession
          }
        },
        expiry: 60 * 60 * 24,
        permissions: [
          {
            type: 'contract-call',
            data: {
              address: '0x2522f4fc9af2e1954a3d13f7a5b2683a00a4543a',
              calls: []
            },
            policies: []
          }
        ],
      },
    ],
  });
  ```

  #### Integration with Web3 Libraries

  Popular web3 libraries provide convenient methods for registering session keys:

  | Library | Method                                                                                            |
  | ------- | ------------------------------------------------------------------------------------------------- |
  | Viem    | [Use the `wallet_grantPermissions` action](https://viem.sh/experimental/erc7715/grantPermissions) |
</span>

<span id="openfort-sdk" className="hidden [&>*]:mb-6!">
  ### Openfort SDK method

  :::info
  There are two types of session keys in Openfort: client session keys and server session keys.

  * **Client session keys** are created on the client side and are used to mint assets with a player's smart account.
  * **Server session keys** are created on the client by a key pair and send the address computed to the server.
  :::

  #### 1. Create a Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

  :::note
  For a general overview of session keys, see the [Session keys](https://www.openfort.io/blog/technical-dive-session-keys) post. For more information about how to use the session key endpoints, you can visit our [API documentation](https://openfort.apidocumentation.com).
  :::

  After you have authenticated your user with your regular authentication system, you can create a session key for them.
  To create a session key, you need to generate a key pair on the client-side and send the address computed from the public key to your server.

  Using one of the official Openfort client libraries everything is handled for you.

  1. Install the client-side library:

  :::code-group
  ```sh [npm]
  npm install @openfort/openfort-js --save
  ```

  ```sh [yarn]
  yarn add @openfort/openfort-js
  ```

  ```sh [pnpm]
  pnpm add @openfort/openfort-js
  ```
  :::

  2. Initialize Openfort and create a session key:

  ```ts client.ts
  // Set your public key. Remember to switch to your live PUBLIC key in production.
  // See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
  import Openfort from '@openfort/openfort-js'
  const openfort = new Openfort({
    baseConfiguration: {
        publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY"
    }
  });
  ```

  #### 1. Create a Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span>

  Using [ethers](https://www.npmjs.com/package/ethers), you can create a key pair on the server side of you application.

  ```ts
  const sessionKey = ethers.Wallet.createRandom();
  ```

  The parameter `sessionKey` contains the address that you will need to register.

  After creating the session key, you can go ahead and register it.

  #### 2. Register a Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

  To register a session key, first send the address from the session key to your server.
  You can get the address from the session key object created above like this:

  ```ts client.ts
  const address = sessionKey.address;
  ```

  Then, from your server you can make a request to the Openfort API or use one of our server libraries to register the session key.

  Install Openfort in your server-side and initialize it with your secret key.

  :::code-group
  ```sh [npm]
  npm install @openfort/openfort-node
  ```

  ```sh [.NET]
  dotnet add package Openfort.SDK
  ```
  :::

  Initialize with your secret key:

  :::code-group
  ```ts [Node]
  import Openfort from '@openfort/openfort-node'
  const openfort = new Openfort('sk_test_...');
  ```

  ```csharp [.NET]
  using Openfort.SDK;
  using Openfort.SDK.Model;

  var openfort = new OpenfortClient("sk_test_...");
  ```
  :::

  The created session key would be valid since the 25th of May 2023 at 7:50 GMT (timestamp `1685001000`) and last for 1 hour (timestamp `1685001000`).
  For a useful resource to calculate timestamps online, visit [UNIX Timestamp](https://www.unixtimestamp.com/).

  Note how the `externalOwnerAddress` parameter is used to indicate the address of owner of the account that will be created under the specified player. It's only necessary to specify this parameter when the player is doesn't yet have an account in that chain.

  Also, note how a `policy` is used to indicate the policy that will be used to sponsor the gas fees of the transaction to register the session key.

  In this example `externalOwnerAddress` is used to indicate the address of the owner of the account that will be created under the specified player.

  Register the session key using Openfort:

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/sessions \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player=pla_... \
    -d address="0x76e6...9341" \
    -d chainId=80002 \
    -d validUntil=1685004600 \
    -d validAfter=0 \
    -d externalOwnerAddress="0x41e6...9341" \
    -d policy=pol_...
  ```

  ```ts [Node]
  const sessionKeyAddress = '0x76e6...9341'
  const policyId = 'pol_...'
  const playerId = 'pla_...'
  const validUntil = 1685001000
  const validAfter = 0
  const chainId = 80002
  const externalOwnerAddress = '0x41e6...9341'

  const playerSession = await openfort.sessions.create({
    player: playerId,
    address: sessionKeyAddress,
    chainId: chainId,
    validUntil: validUntil,
    validAfter: validAfter,
    policy: policyId,
    externalOwnerAddress: externalOwnerAddress,
  })
  ```
  :::

  After registering the session key, you can see it in the dashboard under the player's page.

  <div align="center">
    <img alt="DashboardRegisterSessionKey" src="https://blog-cms.openfort.io/uploads/dashboard_session_keys_931c5a570a.png" width="70%" height="70%" />
  </div>

  #### 3. Sign the Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

  The owner of the account of the player needs then to authorize the new session key.

  To do so, it needs to sign the `userOperationHash` from the `nextAction` object returned by the API call to register the session key.

  nextAction response object from transaction\_intents

  ```json
  "nextAction": {
      "type": "sign_with_wallet",
      "payload": {
          "signableHash": "0x91b4efe3648c79467f7b50aa9bb1b4eae383a52dd6d741d39ece29ed2ef8362d"
      }
  },
  ```

  Once the content of the `nextAction` parameter above is signed by the owner signer of the account,
  it has to be sent to Openfort using the endpoint `/v1/sessions/:id/signature` as shown below:

  Sign and send the session key registration:

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/sessions/ses_.../signature \
    -H "Authorization: Bearer $YOUR_PUBLISHABLE_KEY" \
    -d signature="xyz..."
  ```

  ```ts [JavaScript]
  await openfort.sendSignatureSessionRequest(
    playerSession.id,
    SIGNED_USED_OP_HASH
  )
  ```
  :::

  #### 4. Using the Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

  After the session key is registered, it can be used to authenticate requests from the player.
  Whenever you create a transaction intent from your backend, a signature will be needed from the session key or owner of the players' smart account.

  Create a transaction intent:

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/transaction_intents \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player=pla_... \
    -d address="0x76e6...9341" \
    -d chainId=80002 \
    -d policy=pol_...
  ```

  ```ts [Node]
  const playerId = 'pla_...'
  const policyId = 'pol_...'
  const contractId = 'con_...'
  const chainId = 80002
  const optimistic = true

  const interaction: Interaction = {
    contract: contractId,
    functionName: 'mint',
    functionArgs: [playerId],
  }
  const transactionIntent = await openfort.transactionIntents.create({
    player: playerId,
    chainId: chainId,
    optimistic: optimistic,
    interactions: [interaction],
    policy: policyId,
  })
  ```
  :::

  After creating the transaction intent, the session key will need to sign the nextAction `userOperationHash` and send it to Openfort.

  To do so, pass the `userOperationHash` to the `sendSignatureTransactionIntentRequest` method of the Openfort client library.
  Load session key and sign a transaction intent:

  ```ts client.ts
  const openfortTransactionResponse =
    await openfort.sendSignatureTransactionIntentRequest(
      collectResponseJSON.data.id,
      userOperationHash
    )
  ```

  #### 5. Revoke a Session Key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span>

  The owner of the account can always revoke the session key.

  To do so, it needs to sign the `userOperationHash` from the `nextAction` object returned by the API call to revoke the session key.

  Create a transaction intent:

  :::code-group
  ```bash [curl]
  curl https://api.openfort.io/v1/sessions/revoke \
    -H "Authorization: Bearer $YOUR_SECRET_KEY" \
    -d player=pla_... \
    -d address="0x76e6...9341" \
    -d chainId=80002 \
    -d policy=pol_...
  ```

  ```ts [Node]
  const playerId = 'pla_...'
  const policyId = 'pol_...'
  const chainId = 80002
  const sessionKeyAddress = '0x76e6...9341'

  const revokeSession = await openfort.sessions.revoke({
    player: playerId,
    address: sessionKeyAddress,
    chainId: chainId,
    optimistic: true,
    policy: policyId,
  })
  ```
  :::

  Sign the transaction to revoke the session key and remove from client side:

  ```ts client.ts
  const openfortTransactionResponse =
    await openfort.sendSignatureTransactionIntentRequest(
      revokeResponseJSON.data.id,
      userOperationHash
    );
  ```
</span>


## Sign Messages with Custodial Wallets

:::note
This guide is for custodial smart accounts. If you are using non-custodial smart accounts, you should use the `Sign Messages`.
:::

Signing and verifying messages for smart accounts is different than with EOAs. There are a few reasons why:

* With an EOA, the address is effectively the public key of the private key used for signing. Therefore, verifying a EOA signature is as simple as [recovering](https://soliditydeveloper.com/ecrecover) the signature and compare the recovered public key with the address.
  * With a smart account, the address is the address of a smart contract that has no cryptographic link to the signing private key. Therefore, you must use [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) to validate the message.

* With an EOA, you don't have to deploy the account. It just exists.
  * Since smart accounts need to be deployed, it may not be clear how you can validate messages against a smart account not yet deployed.

### Signing messages

To sign messages:

```ts server.ts
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.io/developers/configuration/api-keys
const Openfort = require('@openfort/openfort-node').default;
const openfort = new Openfort(YOUR_SECRET_KEY);

const _domain = {
  name: "Openfort",
  version: "0.5",
  chainId: 13337,
  verifyingContract: "0x9b5AB198e042fCF795E4a0Fa4269764A4E8037D2",
};
const types = {
  Mail: [
    { name: "from", type: "Person" },
    { name: "to", type: "Person" },
    { name: "content", type: "string" },
  ],
  Person: [
    { name: "name", type: "string" },
    { name: "wallet", type: "address" },
  ],
};
const mail = {
  from: {
    name: "Alice",
    wallet: "0x2111111111111111111111111111111111111111",
  },
  to: {
    name: "Bob",
    wallet: "0x3111111111111111111111111111111111111111",
  },
  content: "Hello!",
};
const structHash = ethers.utils._TypedDataEncoder.hash(domain, types, mail);

const signature = await openfort.accounts.signPayload({ 
  id: "acc_4194ad24-c818-4e5c-b003-9cc2aa7df53b", 
  hash: structHash,
  domain: domain
  value: mail,
  types: types,
});
```

### Validating signatures

You can validate signatures with [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271). Here's an example with ethers:

```ts client.ts
const ethers = require("ethers");

async function verifySignature(hash, signature, address) {
  let provider = new ethers.providers.JsonRpcProvider(providerUrl);
  const ABI =   {
    inputs: [
      {
        internalType: "bytes32",
        name: "_hash",
        type: "bytes32",
      },
      {
        internalType: "bytes",
        name: "_signature",
        type: "bytes",
      },
    ],
    name: "isValidSignature",
    outputs: [
      {
        internalType: "bytes4",
        name: "",
        type: "bytes4",
      },
    ],
    stateMutability: "view",
    type: "function",
  };
  const iface = new ethers.utils.Interface(ABI);
  const encodedDataDeposit = iface.encodeFunctionData("isValidSignature", [
    hash,
    signature,
  ]);

  const tx = {
    to: address,
    data: encodedDataDeposit,
  };
  return await provider.call(tx);
}

```


## Social Recovery

One of the main hurdles in enhancing gaming experiences within Web3 environments is ensuring player account security. Unlike traditional gaming accounts, where password recovery is straightforward, Web3 accounts often require meticulous management of a seed phrase to prevent loss of access. This can be a daunting task for players, necessitating either a fail-safe method to secure the seed phrase or reliance on a centralized system to handle key management.

:::tip
By default, Openfort is not a guardian. You need to pass the `defaultGuardian` as **true** parameter to register Openfort as a guardian when creating a new smart account when using [create account](https://openfort.apidocumentation.com).
:::

To address this, gaming platforms can implement a "guardian" system. Guardians are trusted entities or mechanisms designated to facilitate the recovery of a player's account. If a player misplaces their access key, they can create a new one and request their guardians to authorize this new key as the account's official access method, effectively regaining control over their account.

This guardian system can be applied in two primary recovery scenarios:

1. **Self-Recovery:** Players have the option to configure their account recovery using another authentication factor they control, such as a hardware passkey or an alternative Web3 wallet. This method empowers players with direct control over their account recovery process, enhancing security and convenience.
2. **Game-Assisted Recovery:** a player might designate the game developer or platform as their guardian. In the event of losing access to their account, the player would reach out to the game's support team, who would then facilitate the account recovery on their behalf.

:::note
For a general overview of social recovery, see the [Recoverable Accounts](https://www.openfort.io/blog/recoverable-accounts) post.
:::

### Configure assisted recovery

This guide will go through all the necessary steps to complete a recovery with Openfort as a guardian. The default implementation of the endpoint includes:

* Threshold: 1:1
* Guardian: Openfort
* Time lock: 2 days

::::steps
#### 1. Set up Openfort (Server side)

Use our official libraries to access the Openfort API from your application:

Install Openfort:

:::code-group
```sh [npm]
npm install @openfort/openfort-node --save
```

```sh [yarn]
yarn add @openfort/openfort-node
```

```sh [pnpm]
pnpm add @openfort/openfort-node
```
:::

Initialize @openfort/openfort-node:

```ts server.ts
const Openfort = require('@openfort/openfort-node').default
const openfort = new Openfort(YOUR_SECRET_KEY)
```

#### 2. Start recovery process

Openfort will perform a Start Recovery operation to recover the account from the current owner to the new owner.

The `policy` parameter is a policy that will be used to sponsor the transaction. You can find more information about policies in our [API documentation](https://openfort.apidocumentation.com).
Bear in mind that this policy needs to have a `account_functions` policy rule to allow the sponsorship of this operation.

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/account/acc_.../start_recovery \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d newOwnerAddress="0x416c...354D" \
  -d policy="pol_..."
```

```ts [Node]
const accountId = 'acc_...';
const policy = 'pol_...';
const newOwnerAddress = '0x416c...354D';
const playerTransferOwnership = await openfort.accounts.startRecovery(
  {
    id: accountId,
    policy: policy,
    newOwnerAddress: newOwnerAddress,
  }
)
```
:::

#### 3. Complete recovery

After complying with the period of time `lockPeriod`, the guardian has a `securityPeriod` to confirm the proposal. In this case, Openfort will submit the needed signature to complete the recovery of the account.

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/account/acc_.../complete_recovery \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d newOwnerAddress="0x416c...354D" \
  -d policy="pol_..."
```

```ts [Node]
const accountId = 'acc_...';
const policy = 'pol_...';
const newOwnerAddress = '0x416c...354D';
const playerTransferOwnership = await openfort.accounts.completeRecovery(
  {
    id: accountId,
    policy: policy,
    newOwnerAddress: newOwnerAddress,
  }
);
```
:::
::::


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Transfer Account Ownership

With Openfort, you can change the ownership of an account from one address to another. Your players can take ownership of their account without ever having to go through exposing a private key. Secure, frictionless, and easy.

There are 2 steps involved in transferring account ownership:

* **transferOwnership**: starts the ownership transfer of the contract to a new account. Called through the API and performed by Openfort.
* **acceptOwnership**: the new owner accepts the ownership transfer. Performed in the client side by the new owner.

Openfort accounts implement [Ownable2Step](https://docs.openzeppelin.com/contracts/4.x/api/access#Ownable2Step) from [Openzeppelin](https://www.openzeppelin.com/) to create a secure way of transferring account ownership. You can check out the code that allows for this behavior in their [GitHub repository](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/Ownable2Step.sol).

:::note
For more information about how to use the sesion key endpoints, you can visit our [API documentation](https://openfort.apidocumentation.com).
Check out our sample with a transfer ownership example: [GitHub source](https://github.com/openfort-xyz/samples/tree/main/ssv-social-nextjs) and [video walkthrough](https://youtu.be/xBzl8hk__P8?t=264).
:::

### Quickstart

This guide will go though all the necessary steps to transfer account ownership.

::::steps
#### 1. Set up Openfort (Server side)

Use our official libraries to access the Openfort API from your application:

Install Openfort Node.js library:

:::code-group
```sh [npm]
npm install @openfort/openfort-node --save
```

```sh [yarn]
yarn add @openfort/openfort-node
```

```sh [pnpm]
pnpm add @openfort/openfort-node
```
:::

Initialize '@openfort/openfort-node' with your secret key:

```ts server.ts
const Openfort = require("@openfort/openfort-node").default;
const openfort = new Openfort(YOUR_SECRET_KEY);
```

#### 2. Request transfer ownership (Server side)

Openfort will perform a [`transferOwnership`](https://docs.openzeppelin.com/contracts/4.x/api/access#Ownable2Step-transferOwnership-address-) operation to transfer the ownership of the account from the current owner to the new owner.

The `policy` parameter is a policy that will be used to sponsor the transaction. You can find more information about policies in our [API documentation](https://openfort.apidocumentation.com).
Bear in mind this policy needs to have a `account_functions` policy rule to allow the sponsorship of this operation.

:::code-group
```bash [curl]
curl https://api.openfort.io/v1/accounts/acc_.../request_transfer_ownership \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d newOwnerAddress="0x416c...354D" \
  -d "policy=pol_..."
```

```ts [Node]
const accountId = "acc_...";
const policy = "pol_...";
const newOwnerAddress = "0x416c...354D";
const playerTransferOwnership =
  await openfort.accounts.requestTransferOwnership({
    id: accountId,
    policy: policy,
    newOwnerAddress: newOwnerAddress,
  });
```
:::

#### 3. Accept account ownership (Client side)

Using [Wagmi](https://wagmi.sh/) React hooks, you can accept the account ownership by performing an [`acceptOwnership`](https://docs.openzeppelin.com/contracts/4.x/api/access#Ownable2Step-acceptOwnership--) operation to the account address.
Find a working example of how to accept account ownership in our GitHub repository [component sample](https://github.com/openfort-xyz/samples/blob/main/ssv-social-nextjs/components/accept-ownership.tsx).

Accept account ownership from client side:

```jsx accept-ownership.tsx
import {
  usePrepareContractWrite,
  useContractWrite,
  useWaitForTransaction,
} from "wagmi";

const { config } = usePrepareContractWrite({
  address: accountAddress,
  abi: [
    {
      inputs: [],
      name: "acceptOwnership",
      outputs: [],
      stateMutability: "nonpayable",
      type: "function",
    },
  ],
  functionName: "acceptOwnership",
});

const { data, write } = useContractWrite(config);

const { isLoading, isSuccess } = useWaitForTransaction({
  hash: data?.hash,
});
```
::::

### Video Tutorial

<VideoSnippet title="Video" src="xBzl8hk__P8" />


export const meta = {
  title: 'Relay.link integration',
  description: 'Learn how to bridge tokens in your game.',
  subtitle: 'Learn how to implement bridging in your app.'
}

## Relay.link Integration

The sample allows you to convert any tokens, using [Relay.link](https://relay.link/). Bridging rates are determined via the bridge provider, and depend on supply and demand of the respective tokens.

### Samples

[**Bridge with Relay**](https://github.com/openfort-xyz/reservoir0x-relay-embeddedwallet) - A quick start guide to integrate smart accounts with Relay Link


export const meta = {
  title: 'Uniswap V3 integration',
  description: 'Learn how to swapping tokens in your game.',
  subtitle: 'Learn how to implement swaps in your app.'
}

## Uniswap V3 Integration

The API allows you to convert any tokens, using [Uniswap V3](https://docs.uniswap.org/sdk/v3/overview). Conversion rates are determined via an Automated Market Maker mechanism, and depend on supply and demand of the respective tokens.

### API

To exchange tokens, simply make a `POST` request to Openfort's exchange API:

```
https://api.openfort.io/v1/exchange
```

In the body of the request:

* Include the contract addresses of the desired `tokenInAddress` and `tokenOutAddress` tokens
* Include a `fromAddress` that contains the address from which the token is swapped.
* Include an `amount` to swap, either a desired input and output token amount.

Depending on the "direction" of the conversion, there are two different `tradeType`s, which are covered with examples below too. Let's assume we have two tokens IN and OUT:

#### Converting with an exact input amount

* The player wants to swap 100 IN to OUT:

1. we first need to get the amount of OUT we can expect to get for 100 IN.
2. then convert it with an `EXACT_INPUT` to make sure we get the highest amount of OUT for our 100 IN.

#### Converting with an exact output amount

* The player wants to buy 10 OUT:

1. here we first fetch the required amount of IN to obtain 10 OUT.
2. then convert it with an `EXACT_OUTPUT` to make sure get exactly 10 OUT.

Below is a sample cURL command for generating a new wallet for a user with Openfort:

```bash
curl https://api.openfort.io/v1/exchange \
  -u "$YOUR_SECRET_KEY:" \
  -d 'chainId=80002' \
  -d 'fromAddress="0x45..."' \
  -d 'tokenInAddress="0x45..."' \
  -d 'tokenOutAddress="0x45..."' \
  -d 'amount="100000"' \
  -d 'tradeType=EXACT_INPUT'
```

A successful response will include the new user object along with their user's ID (`playerID`), like below:

```json
{
  "id": "tin_c502d628-5bb3-42f2-b8f5-62ba4d71df3a",
  "createdAt": 1689869074,
  "object": "transactionIntent",
  "abstractionType": "accountAbstractionV6",
  "details": {
    "userOperationHash": "0x25d3...005c",
    "userOperation": {
      "sender": "0x48930Cd730652bf0B18Ef8c80cD0Fa1Cc72A233E",
      "nonce": "0x2",
      "initCode": "0x",
      "callData": "0xb61d...0000",
      "callGasLimit": "0x27863",
      "verificationGasLimit": "0x16001",
      "preVerificationGas": "0xb818",
      "maxFeePerGas": "0x62590091",
      "maxPriorityFeePerGas": "0x62590091",
      "paymasterAndData": "0x3210...b51c",
      "signature": "0x6202...3d1b"
    },
  },
  "chainId": 80002,
  "updatedAt": 1689869074,
  "policy": {
    "id": "pol_..."
  },
  "player": {
    "id": "pla_..."
  },
  "account": {
    "id": "acc_..."
  },
  "response": {
    "createdAt": 1689869074,
    "logs": [
      {
        "removed": false,
        "transactionIndex": 0,
        "blockNumber": 44904492,
        "transactionHash": "0x25d3...005c",
        "address": "0x5FF1...2789",
        "topics": [
          "0xbb47...f972"
        ],
        "data": "0x",
        "logIndex": 0,
        "blockHash": "0x8a69...6d59"
      }
    ],
    "blockNumber": 8789286,
    "transactionHash": "0x25d3...005c",
    "to": "0x0576...1B57",
    "gasUsed": "336730",
    "status": 1
  },
  "interactions": [
    {
      "functionName": "mint",
      "value": "100000000000000",
      "contract": "0x0576...1B57",
      "functionArgs": [
        "0x63B7...484f"
      ]
    }
  ]
}
```

:::note
Check the [Quote Swap endpoint](https://openfort.apidocumentation.com) to get a quotation before executing the conversion.
:::


## Hooks

### useStatus

The `useStatus` hook provides the current status of the Openfort SDK. The status can be one of the following:

* `LOADING`: The SDK is loading
* `CONNECTED`: The user is connected
* `DISCONNECTED`: The user is disconnected
* `NEEDS_RECOVERY`: The SDK needs the recovery phrase to be entered.
* `DISCONNECTED_WITH_ADDRESS`: The SDK is disconnected with an address. This can happen when the user has connected to a Web3 wallet without connecting to Openfort.

It also provides helpful boolean values to check the status, like `isConnected` or `isLoading`.

```jsx
import { useStatus } from "@openfort/openfort-kit";

function App() {
  const { status, isConnected, isLoading } = useStatus()
}
```

### useUser

Hook to get the current user. It returns the following properties:

* `user`: The user object.
* `getAccessToken`: A function to get the access token. It will return the access token if the user is connected, if it is expired it will refresh the token.
* `validateAndRefreshToken`: A function to validate and refresh the access token. It will return the new access token if the user is connected.

```jsx
import { useUser } from "@openfort/openfort-kit";

function App() {
  const { user, getAccessToken, validateAndRefreshToken } = useUser()
}
```

The user object contains combines the user's information with the Openfort player `id`:

```json
{
  "id": "pla_ff54b031-a878-4ca2-9cf5-ae190f921e9b",
  "object": "player",
  "createdAt": 1691658234,
  "linkedAccounts": [
    {
      "provider": "email",
      "email": "jaume@openfort.io",
      "disabled": false,
      "updatedAt": 1691658234
    }
  ]
}
```

To get the `address` of the user, you would use [wagmi](https://wagmi.sh/react/api/hooks)'s `useAccount` hook:

```jsx
import { useAccount } from 'wagmi';

function App() {
  const { address } = useAccount();
}
```

### useProviders

Hook to get the providers. It returns the following properties:

* `linkedProviders`: An array of providers that the user has linked. If user is not connected, the array will be empty.
* `allProviders`: An array of all providers.
* `availableProviders`: An array of providers that the user can link. (All providers except the ones that are already linked)

```jsx
import { useProviders } from "@openfort/openfort-kit";

function App() {
  const { linkedProviders, availableProviders, allProviders } = useProviders();
}
```

### useWallets

Hook to get the wallets liked by the user and available on the current device. It returns the following properties:

* `wallets`: An array of wallets linked by the user.
* `currentWallet`: The current active wallet.
* `setActiveWallet`: A function to set the active wallet.
* `exportPrivateKey`: A function to export the private key of the current active wallet (only available with embedded signer).

```jsx
import { useIsMounted } from "@openfort/openfort-kit";

function App() {
  const { wallets, setActiveWallet, currentWallet, exportPrivateKey } = useWallets()
}
```

### useLogout

Hook to logout the user. It returns a function that you can call to logout the user.

```jsx
import { useLogout } from "@openfort/openfort-kit";

function App() {
  const logout = useLogout();
}
```

### useModal

Hook for controlling the modal. It returns the following functions:

* `setOpen`: Sets the modal open state.
* `openWallets`: Opens the wallets page.
* `openProviders`: Opens the providers page. (Only available if the user is connected)
* `openSwitchNetworks`: Opens the switch networks page. (Only available if the user is connected)

```jsx
import { useModal } from "@openfort/openfort-kit";

function App() {
  const { openSwitchNetworks, setOpen, openProviders, openWallets } = useModal();
}
```

### useChains

Hook to get the chains set in the wagmi configuration. It returns an array of chains.

```jsx
import { useChains } from "@openfort/openfort-kit";

function App() {
  const chains = useChains();
}
```

### useChainIsSupported

Hook to check if a chain is supported. It returns a function that you can call to check if a chain is supported.

```jsx
import { useChains, useChainIsSupported } from "@openfort/openfort-kit";

function App() {
  const chains = useChains();
  const chainIsSupported = useChainIsSupported(chains?.[0]?.id);
}
```

### useIsMounted

Helper hook to check if the component is mounted. It returns a boolean value. Useful for ssr apps.

```jsx
import { useIsMounted } from "@openfort/openfort-kit";

function App() {
  const isMounted = useIsMounted();
}
```


## Openfort Kit Button

To use the Openfort Kit Button, you will need to use the `OpenfortKitButton` component. This component will render a button that will open the Openfort login screen when clicked.

```jsx
import { OpenfortKitButton } from '@openfort/openfort-kit';

function App() {
  return (
    <div>
      <OpenfortKitButton />
    </div>
  );
};
```

This button will use the default configuration of the Openfort Kit, but you can customize the theme properties of the button.

There are other customization properties:

* `showAvatar`: Show the avatar of the user
* `showBalance`: Show the balance of the user
* `label`: The label of the button when the user is not connected

The `OpenfortKitButton` component also provides a `onClick` callback that will be called when the user clicks the button.


## Customize the UI

### Kit Theming

Content for Openfort Kit theming is coming soon.

```jsx
<OpenfortKitProvider theme="YOUR THEME" {/* other props */}>
  {/* Your app here */}
</OpenfortKitProvider>
```

### More customization

Openfort Kit uses ConnectKit, and offers the same theming and customization options. You can edit fonts, colors, and other styling via the theme and customTheme props. For detail, see the [ConnectKit docs](https://docs.family.co/connectkit/customization).


## Configuration

In this guide, we will show you how to use the Openfort Kit configuration to customize the look and feel of the Openfort login screen, configure your signer and more.

To learn more about the provider configuration, go to the [provider configuration page](/docs/products/embedded-wallet/react/kit/setup/provider).

This is a full example of how to use the `OpenfortKitProvider` with password authentication and a `retro` theme, using `beamTestnet` and `polygonAmoy` chains.

```jsx
import React from 'react';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthProvider, OpenfortKitProvider, RecoveryMethod, getDefaultConfig } from '@openfort/openfort-kit';
import { beamTestnet, polygonAmoy } from 'viem/chains';
import { WagmiProvider, createConfig } from 'wagmi';
import CustomLogo from './CustomLogo';

const config = createConfig(
  getDefaultConfig({
    appName: 'OpenfortKit Next.js demo',
    chains: [beamTestnet, polygonAmoy],

    walletConnectProjectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID,
  })
);

const queryClient = new QueryClient();

export const Web3Provider = ({ children }: { children: React.ReactNode }) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <OpenfortKitProvider

          // Set the publishable key of your OpenfortKit account. This field is required.
          publishableKey={process.env.NEXT_PUBLIC_OPENFORT_PUBLIC_KEY}

          // Set the wallet configuration. In this example, we will be using the embedded wallet.
          walletConfig={{
            createEmbeddedSigner: true,

            embeddedSignerConfiguration: {
              shieldPublishableKey: process.env.NEXT_PUBLIC_SHIELD_API_KEY,

              // Set the recovery method you want to use, in this case we will use the automatic recovery method
              recoveryMethod: RecoveryMethod.AUTOMATIC,

              // Set the encryption key endpoint to encrypt the recovery data
              createEncryptedSessionEndpoint: '/api/protected-create-encrypted-session',

              // You can set a policy id to sponsor the gas fees for your users
              ethereumProviderPolicyId: process.env.NEXT_PUBLIC_POLICY_ID,
            }
          }}

          // This is the callback that will be called when the user connects or disconnects
          onConnect={(params) => {
            console.log('onConnect', params);
          }}
          onDisconnect={() => {
            console.log('onDisconnect');
          }}

          options={{
            // You can customize the logo of your app
            logo: (<CustomLogo />),

            // Set the auth providers you want to use
            authProviders: [
              AuthProvider.GUEST,
              AuthProvider.EMAIL,
              AuthProvider.GOOGLE,
              AuthProvider.TWITTER,
              AuthProvider.FACEBOOK,
              AuthProvider.WALLET,
            ],

            // Set the chain id you want to use, by default it will use the first chain
            initialChainId: polygonAmoy.id,

            // Skip the email verification, useful for testing
            skipEmailVerification: true,

            // Other useful options
            overlayBlur: 2.5,
            hideTooltips: true,
          }}

          // Set the theme of the OpenfortKit
          theme="retro"
        >
          {children}
        </OpenfortKitProvider>
      </QueryClientProvider>
    </WagmiProvider >
  );
};

```

### OpenfortKitButton

The button component that will allow your users to connect to Openfort.

To learn more about the `OpenfortKitButton` component, go to the [button configuration page](/docs/products/embedded-wallet/react/kit/setup/button).

```jsx
import { OpenfortKitButton } from '@openfort/openfort-kit';

function App() {
  return (
    <div>
      <OpenfortKitButton />
    </div>
  );
};

```


## OpenfortKitProvider Configuration

Openfort Kit Provider is the main component that you will use to wrap your application. It will provide the context to all the components that need to interact with the Openfort Kit.

It has the following props:

* `publishableKey`: The Openfort publishable key. You can get it from the [Openfort dashboard](https://dashboard.openfort.io/developers/configuration/api-keys).
* `walletConfig`: Configuration for the Fort wallet. It is explained in the [Wallet Configuration](#wallet-configuration) section.
* `theme`: The theme to be used, default is 'auto'. Learn more about themes in the [Custom UI](/docs/products/embedded-wallet/react/kit/setup/custom-ui) guide.
* `mode`: The theme mode to be used, default is 'auto'.
* `customTheme`: Custom theme configuration.
* `options`: Additional configuration options. It is explained in the [Options Configuration](#options-configuration) section.
* `onConnect`: Callback function to be called on connect.
* `onDisconnect`: Callback function to be called on disconnect.
* `debugMode`: Enable or disable debug mode, default is false.

### Options Configuration

In this section we will describe the most important properties of the `options` object.

#### Auth Providers

The `authProviders` property is an array of `AuthProvider` authentication providers.
Currently, the following providers are supported:

* Guest
* Email
* Wallet
* Google
* Facebook
* Twitter

:::note
Social login configuration - Social login like Google, Facebook, and Twitter require some additional configuration to let Openfort know about your app. You can find more information in the Social login guide.
:::

#### Disclaimer

There are two ways to configure the disclaimer, you can either set the terms of service and privacy policy URLs:

* `privacyPolicyUrl`: The privacy policy URL.
* `termsOfServiceUrl`: The terms of service URL.

or customize the disclaimer component:

* `disclaimer`: A disclaimer to be shown in the wallet.

#### Other options

* `skipEmailVerification`: Skip email verification. Useful for testing.
* `enforceSupportedChains`: This will enforce the supported chains, it will open the modal until the user selects a supported chain.
* `logo`: The logo to be shown in the wallet.
* `openfortUrlOverrides`: The Openfort URL overrides.
* `hideBalance`: Hide the balance in the wallet.
* `hideTooltips`: Hide the tooltips in the wallet.
* `hideRecentBadge`: Hide the recent badge in the wallet.
* `walletConnectCTA`: Show the WalletConnect CTA as a link, modal or both.
* `avoidLayoutShift`: Avoid layout shift when the wallet is loaded.
* `embedGoogleFonts`: Embed Google Fonts in the wallet.
* `truncateLongENSAddress`: Truncate long ENS addresses.
* `walletConnectName`: The name to be used for WalletConnect.
* `reducedMotion`: Enable reduced motion.
* `bufferPolyfill`: Enable buffer polyfill.
* `customAvatar`: Custom avatar component.
* `initialChainId`: The initial chain ID.
* `overlayBlur`: The overlay blur.

### Wallet Configuration

In this section we will describe the properties of the `walletConfig` object.

#### How will the user sign transactions?

There are two ways to configure the wallet, you can either use the **embedded wallet** - a non-custodial wallwt provided by Openfort - or have the user sign transactions with a **web3 provider**.

#### Embedded Wallet

If you are using the embedded wallwt, you will need to set the following properties:

* `createEmbeddedSigner`: Set to `true` to use the embedded wallet.
* `embeddedSignerConfiguration`: The configuration for the embedded wallet. Explained in the [following](#embedded-signer-configuration) section.

#### Embedded Wallet Configuration

The most important properties of the `embeddedSignerConfiguration` object are:

* `shieldPublishableKey`: This is the publishable key of the shield. You can get it from the [Openfort dashboard](https://dashboard.openfort.io/developers/configuration/api-keys).

* `recoveryMethod`: The recovery method you want to use. Currently, the following methods are supported:

  * `RecoveryMethod.AUTOMATIC`
  * `RecoveryMethod.PASSWORD`

  If you need help deciding which method to use, check the [embedded wallet](/docs/products/embedded-wallet/javascript/signer/recovery) guide.

* `ethereumProviderPolicyId`: Optional policy ID when they use the Embedded Wallet. This can be used to sponsor the gas fees for your users. Create one using the [Openfort dashboard](/docs/configuration/sponsor-rules). Learn more about [sponsoring gas fees](/docs/products/embedded-wallet/javascript/smart-wallet/send).

#### Automatic Recovery

If you use automatic recovery, you will need a **backend service** to create an encryption session for the user. This endpoint should be protected and only accessible by the user who is requesting the encryption session (i.e. the user who is logging in).

For example, in a Next.js API route, you can create an endpoint like this:

:::code-group
```ts [protected-create-encryption-session.ts]
import openfort from './openfortAdminConfig';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
    const session = await openfort.registerRecoverySession('YOUR_SHIELD_PUBLISHABLE_KEY', 'YOUR_SHIELD_SECRET_KEY', 'YOUR_SHIELD_ENCRYPTION_SHARE')
    res.status(200).send({
        session: session,
    });
}
```

```ts [openfortAdminConfig.ts]
import Openfort from '@openfort/openfort-node';

const openfort = new Openfort('YOUR_OPENFORT_SECRET_KEY');

export default openfort;
```
:::

In the `embeddedSignerConfiguration` you will need to specify one of the following properties:

* `createEncryptionSessionEndpoint`: the URL of the endpoint you created
* `getEncryptionSession`: the function that will return the encrypted session.

{/* TODO: ADD EXAMPLES */}

#### Password Recovery

If you use password recovery, you can set the `shieldEncryptionKey` property with the encryption key to encrypt the recovery data.

You can also create a backend service, the same way as with automatic recovery instead of setting the `shieldEncryptionKey` property.

{/* TODO: ADD EXAMPLES */}

#### Web3 Provider

If you don't want to use the embedded wallet, you can use a web3 provider. You will need to enable `AuthProvider.Wallet` in the `authProviders` array, and make the users sign transactions with their web3 provider:

* `linkWalletOnSignUp`: This will ensure that the user links their wallet on sign up.


## Wagmi configuration

Openfort Kit uses [wagmi](https://wagmi.sh/) internally and therefore it's possible to use hooks from wagmi to fetch data such as info about the connected account.

Here is an example of how you can set up the wagmi configuration:

```jsx
const config = createConfig(
  getDefaultConfig({
    // Your dApps chains
    chains: [mainnet],
    transports: {
      // RPC URL for each chain
      [mainnet.id]: http(
        `https://eth-mainnet.g.alchemy.com/v2/${process.env.NEXT_PUBLIC_ALCHEMY_ID}`,
      ),
    },

    // Required API Keys
    walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,

    // Required App Info
    appName: "Your App Name",

    // Optional App Info
    appDescription: "Your App Description",
    appUrl: "https://openfort.io", // your app's url
    appIcon: "https://openfort.io/logo.png", // your app's icon, no bigger than 1024x1024px (max. 1MB)
  }),
);
```


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Integrate Firebase with Openfort in Unity

### Overview

[Firebase](https://firebase.google.com/) is Google's all-encompassing app development platform, providing game developers with an array of backend tools powered by Google Cloud.

Within Unity, we've integrated the Firebase SDK to facilitate backend functionalities. Coupled with the [Google Play Games plugin for Unity](https://github.com/playgameservices/play-games-plugin-for-unity), it ensures a secure and efficient login for Android users.

The integration is further enhanced with the [Openfort Firebase extension](https://extensions.dev/extensions/openfort/firestore-openfort-transactions), which incorporates the [Openfort SDK](https://github.com/openfort-xyz/openfort-node). This enables Unity clients to directly leverage Openfort's blockchain capabilities, allowing for sophisticated blockchain interactions within the gaming environment.

<VideoSnippet title="Video" src="3DOZhuqKdG0" />

### Application Workflow

<div align="center">
  <img alt="Integration workflow" src="https://blog-cms.openfort.io/uploads/firebase_integration_workflow_f549a770b3.png" width="100%" height="100%" />
</div>

### Prerequisites

* Sign in to [dashboard.openfort.io](http://dashboard.openfort.io) and create a new project.

* You need a [Google Play Developer account](https://support.google.com/googleplay/android-developer/answer/6112435?hl=en).

* You need a [Google Cloud project](https://developers.google.com/workspace/guides/create-project).

* Clone or download the repository and open it with Unity [2021.3](https://unity.com/releases/editor/qa/lts-releases?version=2021.3).
  When opening the project, select ***Ignore*** on this popup:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_03a708cc91.png?updated_at=2023-11-07T18:41:24.181Z" alt="ignore popup" />
  </div>

  Once opened, you will see some reference errors. We will solve this in the next step by importing the Firebase SDK.

* Follow the [Firebase-Unity setup guide](https://firebase.google.com/docs/unity/setup?hl=es-419).
  On [step 4](https://firebase.google.com/docs/unity/setup?hl=es-419#add-sdks), you just need to import ***FirebaseAuth*** and ***FirebaseFirestore*** packages:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_1_7d8a33fb8d.png?updated_at=2023-11-07T18:41:24.676Z" alt="import Firebase packages" />
  </div>

  Do it one by one and disable ***ExternalDependencyManager*** folder before importing:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_2_352fc42325.png?updated_at=2023-11-07T18:41:37.181Z" alt="import unity package" />
  </div>

  Most reference errors should be solved by now. If `UnityEditor.iOS.Extensions.Xcode` error is still standing, select ***Firebase.Editor*** asset, disable ***Validate References*** and choose ***Apply***:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_3_9ea2133564.png?updated_at=2023-11-07T18:41:46.887Z" alt="resolve packages" />
  </div>

* Create a keystore
  Follow this [guide](https://docs.unity3d.com/Manual/android-keystore-create.html) to create a new keystore for the Unity project.

* Find SHA1 certificate fingerprint
  You need to extract the certificate fingerprint from the created keystore. Follow this [video tutorial](https://www.youtube.com/watch?v=lDXE4lfM0aQ) on how to do it, it also covers the creation of the keystore.

  This is the command that you will need to run:

  ```shell
  keytool -list -v -keystore "path/to/your/keystore" -alias "your_key_alias"
  ```

### Set up Firebase

#### Add Google sign-in provider

Go to the [Firebase console](https://console.firebase.google.com/?hl=es-419), select your project and select ***Authentication***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_4_e8b0d867f8.png?updated_at=2023-11-07T18:41:47.295Z" alt="setup authentication firebase" />
</div>

After selecting ***Get started***, select ***Google*** as a sign-in provider:

<div align="center">
  <img width="80%" height="80%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_6_eacbe66a92.png?updated_at=2023-11-07T18:41:38.487Z" alt="choose the auth method" />
</div>

Activate ***Enable*** toggle, choose a public-facing name and select ***Save***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_7_4b75cbc33e.png?updated_at=2023-11-07T18:41:40.678Z" alt="setup google" />
</div>

A popup will appear. Copy the ***Web client ID*** and the ***Web client secret*** somewhere safe and choose ***Done***. You will see your Google provider enabled:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_8_7d2b07af1c.png?updated_at=2023-11-07T18:41:29.178Z" alt="enabled google" />
</div>

Select the provider and choose ***Project Settings***. Under ***Your apps*** section select ***Add fingerprint*** and add your [SHA1 certificate fingerprint](https://github.com/openfort-xyz/firebase-extension-unity-sample/tree/main#find-sha1-certificate-fingerprint). Then choose ***Save***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_26_0877bd3b91.png?updated_at=2023-11-07T18:41:44.183Z" alt="add fingerprint" />
</div>

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_27_9505073e7c.png?updated_at=2023-11-07T18:41:29.584Z" alt="certificate for SHA1" />
</div>

#### Add Google Play sign-in provider

Select ***Add new provider*** and choose ***Google Play***:

<div align="center">
  <img width="80%" height="80%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_9_7c803a1a83.png?updated_at=2023-11-07T18:41:36.279Z" alt="Choose Google Play" />
</div>

Activate ***Enable*** toggle, enter the credentials you just saved and choose ***Save***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_10_3cd041e888.png?updated_at=2023-11-07T18:41:33.579Z" alt="Play games setup" />
</div>

Both ***Google*** and ***Google Play*** sign-in providers are ready:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_11_0a946e50ff.png?updated_at=2023-11-07T18:41:31.578Z" alt="auth providers" />
</div>

#### Install Openfort Extension

Go to the [Firebase Extensions Hub](https://extensions.dev/extensions/openfort/firestore-openfort-transactions) and choose ***Install in Firebase console***:

<div align="center">
  <img width="80%" height="80%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_37_663d8ce948.png?updated_at=2023-11-07T18:41:43.778Z" alt="extension hub" />
</div>

Choose your project to continue:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_38_129ce9d653.png?updated_at=2023-11-07T18:41:44.982Z)

Set up your billing profile and follow the instructions until you need to insert the [Openfort API Secret key](https://dashboard.openfort.io/developers/configuration/api-keys) and choose ***Create secret***. Also set *Cloud Firestore* to ***Sync***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_39_97fd67c417.png?updated_at=2023-11-09T04:43:58.995Z" alt="configure extension" />
</div>

Finally choose ***Install extension***. After 3-5 minutes you will see the extension installed:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_41_9c8adab805.png?updated_at=2023-11-07T18:41:46.977Z)

Now select ***Get started*** and under ***How this extension works*** section find ***Configure Openfort webhooks***. Copy the URL:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_42_c9e5cfa74b.png?updated_at=2023-11-07T18:41:46.182Z" alt="setup webhook" />
</div>

### Set up Openfort

#### [Add webhook](https://dashboard.openfort.io/webhooks)

Choose ***Add webhook***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_40_47d93997bf.png?updated_at=2023-11-07T18:41:38.486Z)

Paste the webhook URL you got from the Firebase extension and leave the *Type* as it is. Choose ***Add webhook***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_44_f0baf395ee.png?updated_at=2023-11-07T18:41:44.581Z)

#### [Add a Contract](https://dashboard.openfort.io/contracts/new)

Choose ***Add contract***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_45_dff8dbd5d9.png?updated_at=2023-11-09T04:23:43.095Z)

This sample requires a contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (NFT contract deployed in 80002 Amoy). You can use the same for this tutorial:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_46_05a8645885.png?updated_at=2023-11-09T04:25:24.000Z)

#### [Add a Policy](https://dashboard.openfort.io/policies/new)

Choose ***Add policy***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_47_e043788f2d.png?updated_at=2023-11-09T04:27:17.395Z)

We aim to cover gas fees for users. Set a new gas policy:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_48_3cd0914ae9.png?updated_at=2023-11-09T04:31:49.793Z)

Now, add a rule so our contract uses this policy:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_49_74f55004ba.png?updated_at=2023-11-09T04:31:50.888Z)

### Set up Google Play

> **Reminder:** Use the same Google account you used for setting up your Firebase app.

#### Create a new app

Go to [Play Console](https://play.google.com/console) and create a new app. Enter app details (it's important you select ***Game***), confirm policies and select ***Create app***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_12_0487318190.png?updated_at=2023-11-07T18:41:44.580Z)

Under ***Grow --> Play Games Services --> Setup and management --> Configuration***, select ***Create new Play Games Services project*** and choose your Firebase project as the cloud project. Then select ***Use***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_13_5ad11592ff.png?updated_at=2023-11-07T18:41:47.787Z)

#### Add credentials

##### Add Android OAuth client credential

Under ***Credentials*** section choose ***Add credential***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_14_7e4b6cb5d1.png?updated_at=2023-11-07T18:41:46.982Z)

Select ***Android***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_15_a46a653f09.png?updated_at=2023-11-07T18:41:46.784Z" alt="add android credential" />
</div>

Scroll down and select ***Create OAuth client***:

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_16_27ab5da789.png?updated_at=2023-11-07T18:41:33.186Z" alt="create OAuth client" />
</div>

Choose ***Create OAuth Client ID***:

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_17_c6d544e6c4.png?updated_at=2023-11-07T18:41:31.682Z" alt="create OAuth client popup" />
</div>

This will open the Google Cloud console. Now select ***Android*** as *Application type*, enter a *Name* and fill the *Package name* with the **Unity app package name** (found in the Android Platform Player Settings):

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_19_72b69ccb8c.png?updated_at=2023-11-07T18:41:46.678Z" alt="setup client id gcp" />
</div>

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_20_e3286e880c.png?updated_at=2023-11-07T18:41:47.076Z)

Enter your [SHA1 certificate fingerprint](https://github.com/openfort-xyz/firebase-extension-unity-sample/tree/main#find-sha1-certificate-fingerprint) and choose ***CREATE***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_21_b1c2c44246.png?updated_at=2023-11-07T18:41:34.781Z" alt="verify SHA1 create" />
</div>

Now you can download the JSON and choose ***OK***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_22_ee531ceeba.png?updated_at=2023-11-07T18:41:36.781Z" alt="download JSON" />
</div>

Go back to the Google Play console, select ***Done*** and choose your newly created Android OAuth client. Then select ***Save changes***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_23_5ff3dc73de.png?updated_at=2023-11-07T18:41:44.877Z)

##### Add Game server/Web OAuth client credential

Go back to ***Configuration*** and select ***Add credential***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_24_b44fc158b9.png?updated_at=2023-11-07T18:41:44.287Z)

Choose ***Game server***, refresh OAuth clients, select ***Web client (auto created by Google Service)*** (it was created automatically during [this process](https://github.com/openfort-xyz/firebase-extension-unity-sample/tree/main#add-google-sign-in-provider)) and select ***Save changes***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_25_1f76c7f29a.png?updated_at=2023-11-07T18:41:45.679Z)

Finally copy the ***OAuth client ID***:

<div align="center">
  <img width="70%" height="70%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_28_ecba674180.png?updated_at=2023-11-07T18:41:30.082Z" alt="copy the oauth client" />
</div>

### Set up Unity project

> **Reminder:** Make sure ***Android*** is selected as a platform in ***Build settings***.

Go to ***Window --> Google Play Games --> Setup --> Android setup***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_30_818b8cbf6d.png?updated_at=2023-11-07T18:41:35.884Z)

Paste the ***Game server OAuth client ID*** you just copied under ***Client ID***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_31_421e75f3b2.png?updated_at=2023-11-07T18:41:32.077Z" alt="setup google play games" />
</div>

Go to the [Google Play console](https://play.google.com/console) and on your app's configuration select ***Get resources***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_32_52815075fc.png?updated_at=2023-11-07T18:41:44.377Z)

Copy the Android (XML):

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_33_6690691229.png?updated_at=2023-11-07T18:41:38.876Z)

In Unity, paste it in ***Resources Definition*** and then select ***Setup***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_31_421e75f3b2.png?updated_at=2023-11-07T18:41:32.077Z" alt="setup google play games" />
</div>

Finally, go to the [Firebase console](https://console.firebase.google.com/?hl=es-419) and under your app configuration, download the ***google-services.json***:

![Alt text](https://blog-cms.openfort.io/uploads/firebase_extension_unity_img_36_5048e220db.png?updated_at=2023-11-07T18:41:46.980Z)

Import it in your Unity project ***Assets*** folder to make sure every credential is up to date.

### Test on Android

Upon building and running the game on an Android device, the registration/login process is automated via Google Play Games, resulting in a streamlined user experience.

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and Firebase. Always remember to test every feature before deploying to guarantee a flawless player experience.

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/firebase-extension-unity-sample/issues).

If you have questions, comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Integrate PlayFab in Unity

### Overview

[PlayFab](https://playfab.com/) is a backend service provided by Microsoft for game developers, offering tools for live game management, all powered by Azure's cloud infrastructure.

In this sample we use PlayFab's email & password authentication method to register a new user or log in with an existing one. Once authenticaded we use PlayFab's user identity token to create a non-custodial account using [Embedded Smart Accounts](https://www.openfort.io/blog/embedded-smart-accounts).

Moreover, by integrating the [Openfort SDK](https://github.com/openfort-xyz/openfort-node) into Azure Functions, we establish a seamless connection to PlayFab. Unity clients using the PlayFab Unity SDK can tap into these functions, accessing the full range of Openfort features within the game environment.

<VideoSnippet title="Video" src="D_Ezeb4-U08" />

### Application Workflow

<div align="center">
  <img width="100%" height="100%" src="https://blog-cms.openfort.io/uploads/playfab_integration_workflow_43cf69904d.png?updated_at=2024-10-17T11:56:43.141Z" alt="Openfort PlayFab integration workflow" />
</div>

### Prerequisites

* [Create a PlayFab account and title](https://learn.microsoft.com/en-us/gaming/playfab/gamemanager/quickstart)
* Set up your Azure development environment:
  * [Configure your environment](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-vs-code-node?pivots=nodejs-model-v4#configure-your-environment)
  * [Sign in to Azure](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-vs-code-node?pivots=nodejs-model-v4#sign-in-to-azure)
  * [Create a function app](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-vs-code-node?pivots=nodejs-model-v4#create-the-function-app-in-azure)
* [Sign in to dashboard.openfort.io](http://dashboard.openfort.io) and create a new project
* Download or clone the [sample project](https://github.com/openfort-xyz/playfab-unity-sample):
  * Open [unity-client](https://github.com/openfort-xyz/playfab-unity-sample/tree/main/unity-client) with Unity
  * Open [azure-backend](https://github.com/openfort-xyz/playfab-unity-sample/tree/main/azure-backend) with VS Code

### Set up Openfort

1. ##### [Add PlayFab as a provider](https://dashboard.openfort.io/players/auth/providers)

   Add your PlayFab title and choose ***Save***:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_provider_750b4ed963.png?updated_at=2024-03-20T08:07:36.965Z" alt="PlayFab provider" />
   </div>

2. ##### [Create Shield Keys](https://dashboard.openfort.io/developers/configuration/api-keys)

   In order to create secure non-custodial accounts for our players, we need to create [Shield Keys](https://www.openfort.io/configuration/api-keys#shield-secret-and-publishable-keys):

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_1_a_fd65cb50f3.png?updated_at=2024-10-17T10:03:12.057Z" alt="playfab_integration_1_a_fd65cb50f3" />
   </div>

   After the creation, it's very important you save **Shield Encryption Share Key**, you will need it later:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_1_b_b57537dc82.png?updated_at=2024-10-17T10:03:12.650Z" alt="playfab_integration_1_b_b57537dc82" />
   </div>

3. ##### [Add a Contract](https://dashboard.openfort.io/contracts)

   This sample requires a contract to run. We use [0x51216BFCf37A1D2002A9F3290fe5037C744a6438](https://sepolia.etherscan.io/address/0x51216BFCf37A1D2002A9F3290fe5037C744a6438) (NFT contract deployed in Sepolia - 11155111). You can use the same to ease up things:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_1_95cbd5e3b9.png?updated_at=2024-10-17T09:13:44.426Z" alt="playfab_integration_1_95cbd5e3b9" />
   </div>

4. ##### [Add a Policy](https://dashboard.openfort.io/policies/new)

   We aim to cover gas fees for users. Set a new gas policy:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_2_dc0ec65caa.png?updated_at=2024-10-17T09:13:44.439Z" alt="playfab_integration_2_dc0ec65caa" />
   </div>

   Now, add a rule to make our contract benefit from it:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_3_8c21c821c5.png?updated_at=2024-10-17T09:13:44.439Z" alt="playfab_integration_3_8c21c821c5" />
   </div>

### Deploy Azure Backend

Open [azure-backend](https://github.com/openfort-xyz/playfab-unity-sample/tree/main/azure-backend) with VS Code and sign in to Azure:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_4_7deea77cf3.png?updated_at=2024-10-17T09:22:01.129Z" alt="playfab_integration_4_7deea77cf3" />
</div>

Ensure your Function App (here, it's "openfort-playfab") is listed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_5_6d5e73b886.png?updated_at=2024-10-17T09:22:01.428Z" alt="playfab_integration_5_6d5e73b886" />
</div>

In the terminal, run:

```
npm install
```

In the explorer, right-click on a function and select ***Deploy to Function App***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_6_ffc63d55ed.png?updated_at=2024-10-17T09:22:01.628Z" alt="playfab_integration_6_ffc63d55ed" />
</div>

Next, choose your Function App:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_7_977d0a46c8.png?updated_at=2024-10-17T09:22:00.931Z" alt="playfab_integration_7_977d0a46c8" />
</div>

Then, click on ***Deploy***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_8_1119fa1634.png?updated_at=2024-10-17T09:22:01.232Z" alt="playfab_integration_8_1119fa1634" />
</div>

Navigate to your [Azure Portal](https://portal.azure.com/#home) and open your Function App. You should see all the functions listed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_9_fb12c55de4.png?updated_at=2024-10-17T09:29:35.428Z" alt="playfab_integration_9_fb12c55de4" />
</div>

Click on any function and select ***Get Function Url***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_10_c4ebde5781.png?updated_at=2024-10-17T09:29:35.242Z" alt="playfab_integration_10_c4ebde5781" />
</div>

Subsequently, add this URL (along with all others) to PlayFab to enable access to our Azure Functions from within PlayFab.

### Set up PlayFab Title

1. ##### Register Azure Functions

   Visit the [PlayFab developer dashboard](https://developer.playfab.com/), choose your title, and click on ***Automation***:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_11_5615028c17.png?updated_at=2024-10-17T09:36:46.329Z" alt="playfab_integration_11_5615028c17" />
   </div>

   Our functions are already registered. To do the same, click ***Register function*** and provide the function name along with its URL:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_12_644b97fdaf.png?updated_at=2024-10-17T09:36:45.831Z" alt="playfab_integration_12_644b97fdaf" />
   </div>

   Repeat this for all deployed functions.

### Set up Azure Backend

Our Azure backend requires environment variables from both PlayFab and Openfort. Let's configure them.

1. ##### Add Openfort Environment Variables

   * Navigate to the [Azure Portal](https://portal.azure.com/#home) and select your Function App.
   * Under ***Settings --> Environment variables***, click ***Add***:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_13_c828ed6ed8.png?updated_at=2024-10-17T09:45:44.934Z" alt="playfab_integration_13_c828ed6ed8" />
   </div>

   * Provide the following details:
     * Name: `OF_API_KEY`
     * Value: [Retrieve the **API Secret key**](https://dashboard.openfort.io/developers/configuration/api-keys)

   * Add another application setting:
     * Name: `OF_SHIELD_PUB_KEY`
     * Value: [Retrieve the **Shield Publishable Key**](https://dashboard.openfort.io/developers/configuration/api-keys)

   * Add another application setting:
     * Name: `OF_SHIELD_SECRET_KEY`
     * Value: [Retrieve the **Shield Secret Key**](https://dashboard.openfort.io/developers/configuration/api-keys)

   * Add another application setting:
     * Name: `OF_SHIELD_ENCRYPTION_SHARE`
     * Value: It's the **Shield Encryption Share Key** you saved before.

   * Add another application setting:
     * Name: `OF_NFT_CONTRACT`
     * Value: [Retrieve the **Contract API ID**](https://dashboard.openfort.io/contracts)

   * Add another application setting:
     * Name: `OF_SPONSOR_POLICY`
     * Value: [Retrieve the **Policy API ID**](https://dashboard.openfort.io/policies)

   * And another application setting:
     * Name: `OF_CHAIN_ID`
     * Value: 11155111

2. ##### Add PlayFab Environment Variables
   * Visit the [PlayFab developer dashboard](https://developer.playfab.com/), select your title, and navigate to ***Settings wheel --> Title settings***:

     <div align="center">
       <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_14_5bc8927522.png?updated_at=2024-10-17T11:03:15.964Z" alt="playfab_integration_14_5bc8927522" />
     </div>

   * In the ***API Features*** section, copy your ***Title ID***:

     <div align="center">
       <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_15_711115c4a8.png?updated_at=2024-10-17T11:03:16.150Z" alt="playfab_integration_15_711115c4a8" />
     </div>

   * Under ***Secret Keys***, note down your ***Secret key***:

     <div align="center">
       <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_16_56663676c7.png?updated_at=2024-10-17T11:03:16.644Z" alt="playfab_integration_16_56663676c7" />
     </div>

   * Return to the [Azure Portal](https://portal.azure.com/#home) and choose your Function App.

   * Under ***Settings --> Environment variables***, click ***Add***:
     * Name: `PLAYFAB_TITLE_ID`
     * Value: \[Your Title ID]

   * Add another application setting:
     * Name: `PLAYFAB_SECRET_KEY`
     * Value: \[Your Secret Key]

After adding all the environment variables, your configuration panel should look like the following. Confirm your changes by clicking ***Save***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_17_6748a73edf.png?updated_at=2024-10-17T11:06:47.553Z" alt="playfab_integration_17_6748a73edf" />
</div>

### Set up Unity Client

This Unity sample project is already equipped with:

* [PlayFab Unity SDK](https://github.com/PlayFab/UnitySDK)
* [Openfort SDK](https://github.com/openfort-xyz/openfort-csharp-unity)

To begin, open [unity-client](https://github.com/openfort-xyz/playfab-unity-sample/tree/main/unity-client) with Unity:

1. ##### Configure PlayFab SDK

   * Navigate to the ***Project*** tab.
   * Search for `PlayFabSharedSettings` and input your PlayFab ***Title ID***:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_18_591d3cad7d.png?updated_at=2024-10-17T11:13:05.455Z" alt="playfab_integration_18_591d3cad7d" />
   </div>

2. ##### Configure Openfort SDK

   * Open the *Login scene* and add the **API Publishable Key** and the **Shield Publishable Key** to the *OpenfortController* config section:

   <div align="center">
     <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_19_24bc025e75.png?updated_at=2024-10-17T11:13:05.251Z" alt="playfab_integration_19_24bc025e75" />
   </div>

### Test in Editor

Play ***Login*** scene, opt for ***Register***, provide an email and password, then click ***Register*** again. This scene should appear:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_20_f934393700.png?updated_at=2024-10-17T11:20:35.838Z" alt="playfab_integration_20_f934393700" />
</div>

Select ***Mint***. After a brief period, you should see a representation of your newly minted NFT:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_21_8213efd860.png?updated_at=2024-10-17T11:20:36.645Z" alt="playfab_integration_21_8213efd860" />
</div>

In the [Openfort Players dashboard](https://dashboard.openfort.io/players), a new player entry should be visible. On selecting this player:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_22_1b307cda7e.png?updated_at=2024-10-17T11:20:36.654Z" alt="playfab_integration_22_1b307cda7e" />
</div>

You'll notice that a `mint` transaction has been successfully processed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_23_eca707b92d.png?updated_at=2024-10-17T11:27:27.546Z" alt="playfab_integration_23_eca707b92d" />
</div>

Additionally, by choosing your **Sepolia Wallet Address**, the explorer will open and by selecting ***NFT Transfers*** tab you'll see the transaction is further confirmed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_24_f29150e8b8.png?updated_at=2024-10-17T11:27:28.651Z" alt="playfab_integration_24_f29150e8b8" />
</div>

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_integration_25_8aa4b7ec6a.png?updated_at=2024-10-17T11:27:28.239Z" alt="playfab_integration_25_8aa4b7ec6a" />
</div>

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and PlayFab. Always remember to test every feature before deploying to guarantee a flawless player experience.

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/playfab-unity-sample/issues).

If you have questions, comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


import { VideoSnippet } from "@/components/VideoSnippet.tsx";

## Integrate Unity Gaming Services (UGS) in Unity

### Overview

This is a sample project to showcase the Openfort integration with [Unity Gaming Services](https://unity.com/solutions/gaming-services), a complete service ecosystem for Unity live games.

The sample includes:

* [**`ugs-backend`**](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/ugs-backend)

  A .NET Core project with [Cloud Code C# modules](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules#Cloud_Code_C#_modules) that implement [Openfort C# SDK](https://www.nuget.org/packages/Openfort.SDK/1.0.21) methods. Hosted in UGS.

* [**`unity-client`**](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/unity-client)

  A Unity sample game that connects to `ugs-backend` through [Cloud Code](https://docs.unity.com/ugs/manual/cloud-code/manual). It uses [Openfort Unity SDK](https://github.com/openfort-xyz/openfort-csharp-unity) to deserialize its responses.

The sample uses [Unity Authentication](https://docs.unity.com/ugs/en-us/manual/kit/manual/get-started) to sign in as a new anonymous player. It then [creates an Openfort player](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/ab1a5f69346910c18ea88579f6fce81cdcde489a/ugs-backend/CloudCodeModules/PlayersModule.cs#L31) and a [custodial account](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/ab1a5f69346910c18ea88579f6fce81cdcde489a/ugs-backend/CloudCodeModules/PlayersModule.cs#L38) using Openfort and it [links it](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/ab1a5f69346910c18ea88579f6fce81cdcde489a/ugs-backend/CloudCodeModules/PlayersModule.cs#L43) to the Unity player. Then the player can frictionlessly [mint an NFT](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/ab1a5f69346910c18ea88579f6fce81cdcde489a/ugs-backend/CloudCodeModules/MintingModule.cs#L26).

<VideoSnippet title="Video" src="Anl9X253RC8" />

### Application Workflow

<div align="center">
  <img alt="Integration workflow" src="https://blog-cms.openfort.io/uploads/ugs_integration_workflow_c592a871cf.png" width="100%" height="100%" />
</div>

### Prerequisites

* **Get started with Openfort**

  * [Sign in](https://dashboard.openfort.io/login) or [sign up](https://dashboard.openfort.io/register) and create a new dashboard project

* **Get started with UGS**
  * [Complete basic prerequisites](https://docs.unity.com/ugs/manual/overview/manual/getting-started#Prerequisites)
  * [Create a project](https://docs.unity.com/ugs/manual/overview/manual/getting-started#CreateProject)

### Setup Openfort dashboard

* [Add a Contract](https://dashboard.openfort.io/contracts/new)

  This sample requires a contract to run. We use [0xbed6a05ce8719bc00db1cc81a814192c82be1bb1](https://mumbai.polygonscan.com/address/0xbed6a05ce8719bc00db1cc81a814192c82be1bb1) (NFT contract deployed in 80002 Amoy). You can use this for the guide:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_4_9397f3633b.png?updated_at=2023-12-14T15:59:33.808Z" alt="Contract Info" />
  </div>

* [Add a Policy](https://dashboard.openfort.io/policies/new)

  We aim to cover gas fees for users. Set a new gas policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_5_ab3d8ad48d.png?updated_at=2023-12-14T15:59:33.985Z" alt="Gas Policy" />
  </div>

  Now, add a rule so our contract uses this policy:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_6_6727e69146.png?updated_at=2023-12-14T15:59:33.683Z" alt="Policy Rule" />
  </div>

### Set up [`ugs-backend`](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/ugs-backend)

* #### Set Openfort dashboard variables

  Open the [solution](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/main/ugs-backend/CloudCodeModules.sln) with your preferred IDE, open [`SingletonModule.cs`](https://github.com/openfort-xyz/ugs-unity-game-services-sample/blob/main/ugs-backend/CloudCodeModules/CloudCodeModules.csproj) and fill in these variables:

  <div align="center">
    <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_1_6001ca1099.png?updated_at=2023-12-13T17:45:19.990Z" alt="Singleton Module" />
  </div>

  * [Retrieve the **Secret key**](https://dashboard.openfort.io/developers/configuration/api-keys)
  * [Retrieve the **Contract API ID**](https://dashboard.openfort.io/contracts)
  * [Retrieve the **Policy API ID**](https://dashboard.openfort.io/policies)

* #### Package Code
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Package_code).

* #### Deploy to UGS
  Follow [the official documentation steps](https://docs.unity.com/ugs/en-us/manual/cloud-code/manual/modules/getting-started#Deploy_a_module_project).

### Set up [`unity-client`](https://github.com/openfort-xyz/ugs-unity-game-services-sample/tree/main/unity-client)

Follow the [official documentation steps](https://docs.unity.com/ugs/manual/kit/manual/get-started#Link_your_project) to link the `unity-client` to your UGS Project ID.

### Test in Editor

Play the **Main** scene and click ***Sign in*** button. After some authentication-related logs, this panel should appear:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_opensea_img_32_35f675ded4.png?updated_at=2023-11-19T11:06:40.788Z" alt="Game Scene" />
</div>

Select ***Mint***. After a brief period, you should see a representation of your newly minted NFT:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_3_181e80ff26.png?updated_at=2023-12-14T10:02:43.778Z" alt="Mint Panel" />
</div>

In the [Openfort Players dashboard](https://dashboard.openfort.io/players), a new player entry should be visible. On selecting this player:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/playfab_opensea_img_34_706b0d267e.png?updated_at=2023-11-19T11:06:46.177Z" alt="Player Entry" />
</div>

You'll notice that a `mint` transaction has been successfully processed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_7_75cf7a4264.png?updated_at=2023-12-14T16:05:01.500Z" alt="Mint Transaction" />
</div>

Additionally, by choosing your **Amoy Account** and viewing ***NFT Transfers***, the transaction is further confirmed:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_8_6b345bd148.png?updated_at=2023-12-14T16:05:00.991Z" alt="Etherscan" />
</div>

Keep in mind that the sample is designed so a player can mint only once. By default, UGS Authentication will use the same player per device. If you want to sign in with a new player check the ***Clear Session Token*** in ***AuthController***:

<div align="center">
  <img width="50%" height="50%" src="https://blog-cms.openfort.io/uploads/ugs_integration_2_b0fae3ec75.png?updated_at=2023-12-14T09:56:42.591Z" alt="Clear Session Token" />
</div>

### Conclusion

Upon completing the above steps, your Unity game will be fully integrated with Openfort and UGS. Always remember to test every feature before deploying to guarantee a flawless player experience.

For a deeper understanding of the underlying processes, check out the [tutorial video](https://youtu.be/PHNodBmbEfA).

### Get support

If you found a bug or want to suggest a new \[feature/use case/sample], please [file an issue](https://github.com/openfort-xyz/ugs-unity-game-services-sample/issues).

If you have questions, or comments, or need help with code, we're here to help:

* on Twitter at [https://twitter.com/openfortxyz](https://twitter.com/openfortxyz)
* on Discord: [https://discord.com/invite/t7x7hwkJF4](https://discord.com/invite/t7x7hwkJF4)
* by email: [support+youtube@openfort.io](mailto\:support+youtube@openfort.io)


import { VideoSnippet } from "@/components/VideoSnippet.tsx";
import { MultiOptionDisplay } from '@/components/MCP/MultiOptionDisplay';

## Using session keys in Unity

In-game keys are specialized access tools assigned with specific in-game permissions, tailored for enhancing gaming experiences. Examples include:

* A key that grants access only to specific game levels or areas.
* A key that allows the use of up to 1000 in-game currency units.
* A key that remains valid for 3 days before expiring.

:::note
For a general overview of session keys, see the [Session keys](https://www.openfort.io/blog/technical-dive-session-keys) post.
:::

:::info
There are two types of session keys in Openfort: client session keys and server session keys.

* **Client session keys** are created on the client side and are used to mint assets with a player's smart account.
* **Server session keys** are created on the client by a key pair and send the address computed to the server.
:::

<VideoSnippet title="Video" src="rh2E02PATlU" />

### Configuration

This section will guide you through the process of registering a session key and using it to mint an asset with a player's smart account.

<MultiOptionDisplay
  options={[
  { id: 'eip1193-signatures', label: 'Create a session key (Client side)' },
  { id: 'openfort-signatures', label: 'Create a session key (Server side)' },
]}
/>

<span id="eip1193-signatures" className="hidden [&>*]:mb-6!">
  #### 1. Create a session key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

  After you have authenticated your user with your regular authentication system, you can create a session key for them.
  To create a session key, you need to generate a key pair on the client-side and send the address computed from the public key to your server.

  Using one of the official Openfort client libraries everything is handled for you.

  1. Install the client-side library:

  Open `Packages/manifest.json` and add these lines:

  ```json
  "com.openfort.sdk": "https://github.com/openfort-xyz/openfort-csharp-unity.git",
  "com.unity.nuget.newtonsoft-json": "3.0.1",
  "com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.3.3"
  ```

  2. Initialize Openfort and create a session key:

  ```csharp client.cs
  using Openfort.OpenfortSDK;
  using Openfort.OpenfortSDK.Model;

  public class LoginSceneManager : MonoBehaviour
  {
    private OpenfortSDK openfort;
    private SessionKey sessionKey;
    private void Start()
    {
      openfort = await Openfort.Init("YOUR_OPENFORT_PUBLISHABLE_KEY");
      sessionKey = openfort.ConfigureSessionKey();
    }
  }
  ```
</span>

<span id="openfort-signatures" className="hidden [&>*]:mb-6!">
  #### 1. Create a session key <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span>

  Using [ethers](https://www.npmjs.com/package/ethers), you can create a key pair on the server side of you application.

  ```ts
  const sessionKey = ethers.Wallet.createRandom();
  ```

  The parameter `sessionKey` contains the address that you will need to register.

  After creating the session key, you can go ahead and register it.
</span>

#### 2. Register a session key - <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

To register a session key, first send the address from the session key to your server.
You can get the address from the session key object created above like this:

```csharp client.cs
string address  = sessionKey.Address;
```

Then, from your server you can make a request to the Openfort API or use one of our server libraries to register the session key.

Install Openfort in your server-side and initialize it with your secret key.

```bash [nodeJS]
npm install @openfort/openfort-node
```

Initialize '@openfort/openfort-node' with your secret key.

```ts [server.ts]
import Openfort from "@openfort/openfort-node";
const openfort = new Openfort("sk_test_...");
```

```bash [.net]
dotnet add package Openfort.SDK
```

Initialize 'Openfort.SDK' with your secret key.

```csharp [server.cs]
using Openfort.SDK;
using Openfort.SDK.Model;

var openfort = new OpenfortClient("sk_test_...");
```

The created session key would be valid since the 25th of May 2023 at 7:50 GMT (timestamp `1685001000`) and last for 1 hour (timestamp `1685001000`).
For a useful resource to calculate timestamps online, visit [UNIX Timestamp](https://www.unixtimestamp.com/).

Note how the `externalOwnerAddress` parameter is used to indicate the address of owner of the account that will be created under the specified player. It's only necessary to specify this parameter when the player is doesn't yet have an account in that chain.

Also, note how a `policy` is used to indicate the policy that will be used to sponsor the gas fees of the transaction to register the session key.

In this example `externalOwnerAddress` is used to indicate the address of the owner of the account that will be created under the specified player.

Register the session key using Openfort:

:::code-group
```bash [Curl]
curl https://api.openfort.io/v1/sessions \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player=pla_... \
  -d address="0x76e6...9341" \
  -d chainId=80002 \
  -d validUntil=1685004600 \
  -d validAfter=0 \
  -d externalOwnerAddress="0x41e6...9341" \
  -d policy=pol_...
```

```ts [nodeJS]
const sessionKeyAddress = "0x76e6...9341";
const policyId = "pol_...";
const playerId = "pla_...";
const validUntil = 1685001000;
const validAfter = 0;
const chainId = 80002;
const externalOwnerAddress = "0x41e6...9341";

const playerSession = await openfort.sessions.create({
  player: playerId,
  address: sessionKeyAddress,
  chainId: chainId,
  validUntil: validUntil,
  validAfter: validAfter,
  policy: policyId,
  externalOwnerAddress: externalOwnerAddress,
});
```
:::

After registering the session key, you can see it in the dashboard under the player's page.

{" "}

<div align="center">
  <img alt="DashboardRegisterSessionKey" src="https://blog-cms.openfort.io/uploads/dashboard_session_keys_931c5a570a.png" width="70%" height="70%" />
</div>

#### 3. Sign the session key - <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

The owner of the account of the player needs then to authorize the new session key.

To do so, it needs to sign the `userOperationHash` from the `nextAction` object returned by the API call to register the session key.

`nextAction` response object from transaction\_intents

```json
"nextAction": {
    "type": "sign_with_wallet",
    "payload": {
        "signableHash": "0x91b4efe3648c79467f7b50aa9bb1b4eae383a52dd6d741d39ece29ed2ef8362d"
    }
},
```

Once the content of the `nextAction` parameter above is signed by the owner signer of the account,
it has to be sent to Openfort using the endpoint `/v1/sessions/:id/signature` as shown below:

Sign and send the session key registration:

```bash [curl]
curl https://api.openfort.io/v1/sessions/ses_.../signature \
  -H "Authorization: Bearer $YOUR_PUBLISHABLE_KEY" \
  -d signature="xyz..."
```

```csharp [client.cs]
await Openfort.SendSignatureSessionRequest(
  playerSession.id,
  SIGNED_USED_OP_HASH
);
```

#### 4. Using the session key - <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span>

After the session key is registered, it can be used to authenticate requests from the player.
Whenever you create a transaction intent from your backend, a signature will be needed from the session key or owner of the players' smart account.

Create a transaction intent:

:::code-group
```bash [Curl]
curl https://api.openfort.io/v1/transaction_intents \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player=pla_... \
  -d address="0x76e6...9341" \
  -d chainId=80002 \
  -d policy=pol_...
```

```ts [nodeJS]
const playerId = "pla_...";
const policyId = "pol_...";
const contractId = "con_...";
const chainId = 80002;
const optimistic = true;

const interaction: Interaction = {
  contract: contractId,
  functionName: "mint",
  functionArgs: [playerId],
};
const transactionIntent = await openfort.transactionIntents.create({
  player: playerId,
  chainId: chainId,
  optimistic: optimistic,
  interactions: [interaction],
  policy: policyId,
});
```
:::

After creating the transaction intent, the session key will need to sign the nextAction `userOperationHash` and send it to Openfort.

To do so, pass the `userOperationHash` to the `sendSignatureTransactionIntentRequest` method of the Openfort client library.
Load session key and sign a transaction intent:

```csharp [client.cs]
await Openfort.SendSignatureTransactionIntentRequest(
  collectResponseJSON.data.id,
  userOperationHash
);
```

#### 5. Revoke a session key - <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Client side</span> <span className="mr-2 dark:bg-gray-400/10 dark:text-gray-400 font-medium bg-gray-200 text-gray-600 rounded-sm p-1 text-xs">Server side</span>

The owner of the account can always revoke the session key.

To do so, it needs to sign the `userOperationHash` from the `nextAction` object returned by the API call to revoke the session key.

Create a transaction intent:

:::code-group
```bash [Curl]
curl https://api.openfort.io/v1/sessions/revoke \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d player=pla_... \
  -d address="0x76e6...9341" \
  -d chainId=80002 \
  -d policy=pol_...
```

```ts [nodeJS]
const playerId = "pla_...";
const policyId = "pol_...";
const chainId = 80002;
const sessionKeyAddress = "0x76e6...9341";

const revokeSession = await openfort.sessions.revoke({
  player: playerId,
  address: sessionKeyAddress,
  chainId: chainId,
  optimistic: true,
  policy: policyId,
});
```
:::

Sign the transaction to revoke the session key and remove from client side:

```csharp client.cs
var openfortTransactionResponse =
  await openfort.sendSignatureTransactionIntentRequest(
    revokeResponseJSON.data.id,
    userOperationHash
  );
```