<!--
Sitemap:
- [Interop SDK Documentation](/index): Build multichain TypeScript apps with interoperable addresses, cross-chain quotes, transfer execution, and order tracking across providers.
- [Install Interop SDK](/installation): Install @wonderland/interop-addresses and @wonderland/interop-cross-chain, then choose the package that fits your multichain app.
- [Addresses Module](/addresses/): Parse, encode, and resolve chain-aware addresses that combine an account, chain, and optional ENS name into one unambiguous identifier.
- [Addresses: Getting Started](/addresses/getting-started): Parse an interoperable address and extract its components — go from a human-readable name like vitalik.eth@eip155:1 to address and chain ID.
- [Addresses: Concepts](/addresses/concepts): How EIP-7930, ERC-7828, and CAIP-350 combine address and chain into a single, unambiguous, validated identifier for multichain apps.
- [Parsing an Interoperable Name](/addresses/example): Walkthrough for wallet developers — extract the raw address and chain ID from an interop address so legacy contracts keep working.
- [Addresses: Advanced Usage](/addresses/advanced-usage): Advanced patterns for interoperable addresses — checksums, validation, error handling, and round-trip conversions between formats.
- [Addresses: API Reference](/addresses/api): Function signatures and types for the interop-addresses package — high-level helpers, name-layer methods, and binary-layer primitives.
- [Cross-Chain Module](/cross-chain/): One open source integration for cross-chain actions — compare quotes across providers, execute orders, and track completion.
- [Cross-Chain: Getting Started](/cross-chain/getting-started): Execute a cross-chain token transfer end-to-end — create a provider, fetch a quote, send the transaction, and track the order to completion.
- [Cross-Chain: Concepts](/cross-chain/concepts): The intent-based architecture behind the cross-chain package and how the SDK unifies heterogeneous bridge providers behind a common interface.
- [Supported Providers](/cross-chain/providers): Supported cross-chain providers (Across, Relay, OIF, Bungee, LiFi Intents) and how to configure each via createCrossChainProvider.
- [Across Provider](/cross-chain/across-provider): Configure and use the Across Protocol provider for cross-chain token transfers via the Across bridge infrastructure.
- [Relay Provider](/cross-chain/relay-provider): Configure and use the Relay Protocol provider for cross-chain transfers, including opt-in gasless execution via EIP-3009 signatures.
- [OIF Provider](/cross-chain/oif-provider): Direct integration with any OIF-compliant solver — submission modes, resource locks, and configuration for Open Intents Framework backends.
- [Bungee Provider](/cross-chain/bungee-provider): Cross-chain token transfers via Bungee — onchain transactions, gasless permit2 flow, and tier-based API access for sandbox or production.
- [LiFi Intents Provider](/cross-chain/lifi-intents-provider): Cross-chain transfers through the LI.FI intent solver marketplace, where competing solvers fulfill deposits at the best available rate.
- [Cross-Chain: Full Example](/cross-chain/example): End-to-end example of executing a cross-chain transfer — setup, quote, approval handling, transaction submission, and order tracking.
- [Cross-Chain: Frontend Integration](/cross-chain/frontend-integration): Wire the cross-chain SDK into a React/Next.js app with wagmi v2 — a useCrossChainSwap hook covering quotes, approvals, and submission.
- [Order Tracking](/cross-chain/order-tracking): Track cross-chain orders from initiation to completion via OIF OrderStatus events, with both onchain and offchain observation strategies.
- [Cross-Chain: Advanced Usage](/cross-chain/advanced-usage): Aggregator patterns for cross-chain transfers — multi-provider quote fetching, sorting strategies, timeouts, and built-in order tracking.
- [Cross-Chain: API Reference](/cross-chain/api): Function signatures and types for the interop-cross-chain package — providers, aggregator, approval service, and order tracking.
-->

# OIF Provider

The [OIF (Open Intents Framework)](https://github.com/BootNodeDev/intents-framework) provider enables direct integration with any OIF-compliant solver. If you have access to a solver's API endpoint, you can integrate cross-chain functionality directly into your application using this provider.

## Configuration

| Field             | Type     | Required | Description                                                                                                |
| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `solverId`        | string   | Yes      | Solver identifier                                                                                          |
| `url`             | string   | Yes      | Solver API endpoint URL                                                                                    |
| `headers`         | object   | No       | Custom HTTP headers                                                                                        |
| `adapterMetadata` | object   | No       | Additional metadata for the solver                                                                         |
| `providerId`      | string   | No       | Custom provider identifier                                                                                 |
| `supportedLocks`  | string\[] | No       | Lock mechanisms to request (e.g. `["oif-escrow"]`, `["compact-resource-lock"]`). Default: `["oif-escrow"]` |
| `submissionModes` | string\[] | No       | Execution modes: `["user-transaction"]`, `["gasless"]`, or both. Default: all modes                        |

:::info\[OIF defaults to all submission modes]

Unlike Relay and Bungee, the OIF provider enables **both submission modes** when `submissionModes` is not set — `"user-transaction"` (user pays gas) and `"gasless"` (solver executes on behalf of the user). The exact order types available also depend on `supportedLocks` (default: `["oif-escrow"]`).

`"user-transaction"` maps to `oif-user-open-v0`; `"gasless"` maps to escrow-based order types (`oif-escrow-v0`, `oif-3009-v0`, `oif-resource-lock-v0`).

To restrict to a specific mode, set it explicitly:

```typescript
// User-pays-gas quotes only
submissionModes: ["user-transaction"];

// Gasless quotes only
submissionModes: ["gasless"];
```

:::

### Lock Mechanism Mapping

The `supportedLocks` option controls which OIF order types the solver returns:

| Lock Mechanism          | OIF Order Types                |
| ----------------------- | ------------------------------ |
| `oif-escrow`            | `oif-escrow-v0`, `oif-3009-v0` |
| `compact-resource-lock` | `oif-resource-lock-v0`         |

`oif-user-open-v0` (user-pays-gas) is controlled by `submissionModes` independently.

## Creating the Provider

```ts twoslash
import { createCrossChainProvider } from "@wonderland/interop-cross-chain";

// Default: oif-escrow lock type, all submission modes
const oifProvider = createCrossChainProvider("oif", {
    solverId: "my-solver",
    url: "https://oif-api.example.com",
});

// Gasless only (escrow-based)
const gaslessProvider = createCrossChainProvider("oif", {
    solverId: "my-solver",
    url: "https://oif-api.example.com",
    supportedLocks: ["oif-escrow"],
    submissionModes: ["gasless"],
});

// User-pays-gas only
const userTxProvider = createCrossChainProvider("oif", {
    solverId: "my-solver",
    url: "https://oif-api.example.com",
    submissionModes: ["user-transaction"],
});
```

## Execution Modes

The provider offers intent-based cross-chain operations with two execution modes:

### Protocol Mode (Gasless)

User signs EIP-712 message, solver executes on their behalf:

```typescript
import { createCrossChainProvider, getSignatureSteps } from "@wonderland/interop-cross-chain";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

const quotes = await oifProvider.getQuotes({
    user: "0xYourAddress",
    input: {
        chainId: 1,
        assetAddress: "0xInputTokenAddress",
        amount: "1000000",
    },
    output: {
        chainId: 42161,
        assetAddress: "0xOutputTokenAddress",
    },
    swapType: "exact-input",
});

const quote = quotes[0];
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const step = getSignatureSteps(quote.order)[0];
const { signatureType, ...typedData } = step.signaturePayload;
const signature = await walletClient.signTypedData(typedData);
await oifProvider.submitOrder(quote, signature);
```

### User Mode (User Pays Gas)

User executes transaction directly:

```typescript
import { getTransactionSteps } from "@wonderland/interop-cross-chain";

const quotes = await oifProvider.getQuotes({
    user: "0xYourAddress",
    input: {
        chainId: 1,
        assetAddress: "0xInputTokenAddress",
        amount: "1000000",
    },
    output: {
        chainId: 42161,
        assetAddress: "0xOutputTokenAddress",
    },
    swapType: "exact-input",
});

const quote = quotes[0];
const step = getTransactionSteps(quote.order)[0];
// walletClient: a viem WalletClient connected to the user's wallet
await walletClient.sendTransaction({
    to: step.transaction.to,
    data: step.transaction.data,
    value: step.transaction.value ? BigInt(step.transaction.value) : undefined,
});
```

## Approvals

`oif-user-open-v0` and `oif-escrow-v0` need an ERC-20 `approve` before the transfer (the latter approves the canonical Permit2 address). `oif-3009-v0` and `oif-resource-lock-v0` do not.

The SDK surfaces what is needed under `quote.order.checks.allowances`. Read it yourself, or pass an `ApprovalService` to the aggregator and the `approve` step is prepended to `order.steps` when the on-chain allowance is short.

For `oif-escrow-v0`, use `InfiniteAmountStrategy`: Permit2 consumes the allowance on every pull, so an exact-amount approval would re-trigger before every order.

```typescript
import {
    createAggregator,
    createApprovalService,
    InfiniteAmountStrategy,
} from "@wonderland/interop-cross-chain";

const aggregator = createAggregator({
    providers: [oifProvider],
    approvalService: createApprovalService({
        rpcUrls: { 8453: "https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY" },
        amountStrategy: new InfiniteAmountStrategy(),
    }),
});
```

See [Automatic ERC-20 Approvals](/cross-chain/advanced-usage#automatic-erc-20-approvals) for the full reference.

## Next Step

See a complete working example: [Full Example](/cross-chain/example)

## References

* [Open Intents Framework](https://github.com/openintentsframework)
* [ERC-7683: Cross Chain Intents](https://www.erc7683.org/)
* [API Reference](/cross-chain/api) — full type definitions for quotes, fees, and orders
* [Concepts](/cross-chain/concepts) — how intent-based transfers work