# Boson Protocol Documentation — full text

> The entire docs site, concatenated. For the structured index, see /llms.txt.

---

# What Boson is

URL: https://www.bosonprotocol.io/docs/

> Boson Protocol is a tokenized-commitment / escrow protocol for selling physical and digital goods, with first-class support for AI agents.

# What Boson is

Boson is a **tokenized-commitment and escrow protocol for commerce**. A seller publishes an _offer_; a buyer _commits_ to it; the protocol holds both parties' deposits in escrow until the buyer _redeems_ and the seller _delivers_. If something goes wrong, a third-party _dispute resolver_ adjudicates.

What makes Boson different from a traditional payment processor:

- **Non-custodial.** Funds are held by an on-chain Diamond contract, not by Boson.
- **One protocol, many surfaces.** TypeScript SDK, hosted MCP server with ~56 tools, embeddable widgets, an x402 escrow stack, a WooCommerce plugin, and a hosted dApp. Pick whichever fits your stack.
- **Agent-native.** Every protocol action is exposed as an MCP tool with a stable schema. Buyer and seller agents can transact autonomously.
- **Multi-chain.** Deployed on Polygon, Mainnet, Base, Optimism, Arbitrum, plus matching testnets.

## Who this is for

These docs are written for **two audiences in parallel**:

- **Developers building human-facing apps.** Marketplaces, e-commerce sites, drop-launches, Shopify-style storefronts. Reach for the [TypeScript SDK](/tooling/core-sdk), [React Kit](/tooling/react-kit), or [embeddable widgets](/tooling/widgets).
- **Developers building AI-agent apps.** Autonomous buyer or seller agents, agent-to-agent commerce, x402 payment rails. Reach for the [MCP server](/tooling/mcp) or the [x402 stack](/tooling/x402).

Anything that's the same for both (offers, exchanges, disputes, networks, signing) lives once in [Protocol concepts](/concepts/model). Everything else is split by *role* (Sellers, Buyers, Dispute Resolvers, Marketplace operators) and shows you the snippet in whichever stack you're using.

## Where to go next

- **Just want to ship something fast?** Pick a [Quickstart](/quickstart/ai-agent-buyer) — each one is 5–15 minutes and ends with a working prototype.
- **Not sure which stack to use?** Read [Pick your integration](/pick-your-integration).
- **Coming from the v2 dApp or WooCommerce plugin?** Those are still supported — see [Sell via the Boson dApp](/build/sellers/dapp) and [Sell via WooCommerce](/build/sellers/woocommerce).
- **Building an agent?** Start with [Build for AI agents → Overview](/agents).
- **Want the API reference?** Jump to [Reference](/reference).

## A note on terminology

Boson uses a handful of jargon terms (rNFT, dACP, voucher, exchange, offer, agent-the-protocol-role vs agent-the-AI). Every term is defined once in the [Glossary](/glossary). If you see a word that's not obvious, hover the inline link or jump there directly.

---

# Buy with an AI agent in 5 minutes

URL: https://www.bosonprotocol.io/docs/quickstart/ai-agent-buyer

> A copy-paste Vercel AI script that connects to Boson's hosted MCP server and buys a test offer on Base Sepolia.

# Buy with an AI agent in 5 minutes

What you'll build: a Node.js script that uses Vercel AI's SDK + the Boson GOAT plugin to autonomously buy a test offer on Base Sepolia.

**Time**: 5 minutes. **Stack**: Node.js 20+, Vercel AI SDK, GOAT, viem. **Network**: Base Sepolia testnet (`configId: "staging-84532-0"`).

## 1. Get a funded testnet wallet

```bash
# Generate a new private key, or use an existing one.
node -e "console.log(require('viem/accounts').generatePrivateKey())"
```

Fund it with Base Sepolia ETH from any public faucet (e.g. [coinbase.com/faucets](https://www.coinbase.com/faucets/base-ethereum-sepolia-faucet)).

## 2. Set up the project

```bash
mkdir boson-agent-buyer && cd boson-agent-buyer
pnpm init
pnpm add ai @ai-sdk/anthropic \
        @bosonprotocol/agentic-commerce \
        @goat-sdk/adapter-vercel-ai \
        @goat-sdk/wallet-viem \
        viem
```

Set two env vars:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export PRIVATE_KEY="0x..."
```

## 3. The script

```ts twoslash
// @noErrors
// agent.ts
import { generateText } from "ai"
import { anthropic } from "@ai-sdk/anthropic"
import { bosonProtocolPlugin } from "@bosonprotocol/agentic-commerce"
import { getOnChainTools } from "@goat-sdk/adapter-vercel-ai"
import { viem } from "@goat-sdk/wallet-viem"
import { createWalletClient, http } from "viem"
import { baseSepolia } from "viem/chains"
import { privateKeyToAccount } from "viem/accounts"

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
})

const tools = await getOnChainTools({
  wallet: viem(walletClient),
  plugins: [
    bosonProtocolPlugin({
      url: "https://mcp-staging.bosonprotocol.io/mcp",
    }),
  ],
})

const result = await generateText({
  model: anthropic("claude-sonnet-4-6"),
  tools,
  maxSteps: 12,
  system: `
    You are a Boson Protocol buyer agent on Base Sepolia (configId staging-84532-0).
    Find an available test offer with a low price, commit to it, and report the exchangeId.
    Do not redeem; just commit.
  `,
  prompt: "Find and commit to one test offer.",
})

console.log(result.text)
```

Run it:

```bash
pnpm tsx agent.ts
```

## What you should see

The agent will:
1. Call `get_offers` to find available offers.
2. Pick one, call `get_supported_tokens` to confirm the payment token.
3. If it's an ERC-20 offer, call `approve_exchange_token`.
4. Call `commit_to_offer`, receive the unsigned tx, sign locally, broadcast.
5. Report the new `exchangeId`.

Expected output:

```
Found offer 123 at 0.001 USDC. Approving USDC… approved. Committing… committed.
Your new exchange: 456.
```

## What just happened

- The GOAT plugin pulled all 56 MCP tools from the hosted server and registered them with the model.
- Every state-changing tool returned an _unsigned_ transaction; the wallet you passed in signed and broadcast each one.
- The model orchestrated the calls — choosing the offer, approving the token, committing — without you writing flow logic.

## Common gotchas

- **No offers found.** The staging environment may be empty. Create your own with [Quickstart → Build a marketplace](/quickstart/marketplace) first.
- **`InvalidExchangeState` on commit.** The offer was voided or sold out between query and commit. Retry; see [Build for AI agents → Idempotency & retry](/agents/idempotency).
- **Subgraph lag.** If you immediately try to read the new exchange you may get nothing for 1–3 blocks. See [Concepts → Eventing & indexing](/concepts/eventing).

## Next

- [Build for AI agents → Overview](/agents) — patterns for production agents.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what's happening under the hood.
- [Reference → MCP tools](/reference/mcp-tools) — every tool's schema.

---

# Embed a commit button in 5 minutes

URL: https://www.bosonprotocol.io/docs/quickstart/commit-button

> Drop a working Boson Commit Widget into any web page with a script tag.

# Embed a commit button in 5 minutes

What you'll build: a working "Buy now" button on an existing webpage that triggers the Boson commit flow. No SDK, no React, no build step.

**Time**: 5 minutes. **Stack**: any HTML page. **Network**: staging (Base Sepolia) by default.

## 1. Find your seller ID and product UUID

If you already have a seller account, look up your `sellerId` and the `productUuid` of the offer you want to sell — for example via the Boson dApp or via:

```ts
const offers = await sdk.getOffers({ where: { seller: yourAddress } })
```

If you don't yet have a seller account, do [Quickstart → Build a marketplace](/quickstart/marketplace) first, or use a public test seller / product (see staging seed data in the [agent-builder repo](https://github.com/bosonprotocol/agent-builder)).

## 2. Drop in the HTML

```html
<!doctype html>
<html>
<head>
  <title>My drop</title>
  <script src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js" async></script>
</head>
<body>
  <h1>Buy my thing</h1>

  <button
    id="boson-commit"
    data-config-id="staging-84532-0"
    data-seller-id="2"
    data-product-uuid="ec00f1a5-2c96-4d22-9d80-2a7c12345678">
    Buy now
  </button>
</body>
</html>
```

That's it. Open the page; click "Buy now"; the widget opens a modal that:
1. Asks the buyer to connect a wallet.
2. Shows the offer details and price.
3. Walks them through approval (if ERC-20) and commit.
4. Returns a voucher (rNFT) to their wallet.

## Production switch

Swap `staging-84532-0` for `production-137-0` (Polygon mainnet) or any other production ConfigId. Full list at [Networks → ConfigIds matrix](/networks/configids).

## Common gotchas

- **Wrong network.** The buyer's wallet must be on the chain that matches `configId`. The widget prompts them to switch.
- **Insufficient gas / token balance.** The widget surfaces the error inline; nothing breaks server-side.
- **CSP blocks.** If your site has a strict Content Security Policy, allow `https://widgets.bosonprotocol.io` for scripts and frames.

## What this doesn't do

- Doesn't persist orders to your backend. Use a [postback URL](/widgets/postback) or listen via [webhooks](/build/marketplace/webhooks).
- Doesn't customize the modal beyond [theming options](/widgets/styling). For full customization, use the [Core SDK](/tooling/core-sdk) directly.

## Next

- [Widgets → Commit Widget](/widgets/commit) for all options.
- [Widgets → Embedding methods](/widgets/embedding) for `<iframe>` and Zoid alternatives.
- [Widgets → Postback URLs & deep links](/widgets/postback) to hook into your backend.

---

# Build a marketplace in 15 minutes

URL: https://www.bosonprotocol.io/docs/quickstart/marketplace

> Next.js + Boson Core SDK — list a product, commit as a buyer, redeem the voucher. End-to-end on Base Sepolia.

# Build a marketplace in 15 minutes

What you'll build: a Next.js app that creates a seller, publishes an offer, lets a buyer commit, and redeems the voucher — all on Base Sepolia.

**Time**: 15 minutes. **Stack**: Next.js 15, TypeScript, ethers v5, Boson Core SDK. **Network**: Base Sepolia (`configId: "staging-84532-0"`).

## 1. Scaffold

```bash
pnpm create next-app boson-market --typescript --app --no-tailwind --no-eslint
cd boson-market
pnpm add @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk @bosonprotocol/metadata @bosonprotocol/ipfs-storage ethers@^5
```

## 2. Create the SDK once, reuse it

```ts twoslash
// @noErrors
// src/lib/boson.ts
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { IpfsMetadataStorage } from "@bosonprotocol/ipfs-storage"
import { validateMetadata } from "@bosonprotocol/metadata"
import { ethers } from "ethers"

const CONFIG_ID = "staging-84532-0" as const
const ENV_NAME = "staging" as const

export function getSdkForSigner(privateKey: string) {
  const provider = new ethers.providers.JsonRpcProvider(
    process.env.NEXT_PUBLIC_RPC_URL,
  )
  const wallet = new ethers.Wallet(privateKey, provider)

  return {
    sdk: CoreSDK.fromDefaultConfig({
      web3Lib: new EthersAdapter(provider, wallet),
      envName: ENV_NAME,
      configId: CONFIG_ID,
      metadataStorage: new IpfsMetadataStorage(validateMetadata, { url: process.env.IPFS_URL! }),
    }),
    wallet,
  }
}
```

## 3. Create a seller and publish an offer

```ts twoslash
// @noErrors
// scripts/seed.ts
import { ethers } from "ethers"
import { getSdkForSigner } from "../src/lib/boson"

const { sdk, wallet } = getSdkForSigner(process.env.SELLER_PRIVATE_KEY!)

// 1. Create the on-chain seller (if you don't already have one)
const tx1 = await sdk.createSeller({
  assistant: wallet.address,
  admin: wallet.address,
  treasury: wallet.address,
  contractUri: "ipfs://Qm…",
  royaltyPercentage: "0",
  authTokenId: "0",
  authTokenType: 0,
  metadataUri: "ipfs://Qm…",
})
const receipt1 = await tx1.wait()
await sdk.waitForGraphNodeIndexing(receipt1.blockNumber)

const seller = (await sdk.getSellersByAddress(wallet.address))[0]
console.log("Seller created:", seller.id)

// 2. Build and pin metadata. There is no productV1MetadataFactory — construct
//    the PRODUCT_V1 object directly per the schema. See Reference → Metadata.
const uuid = crypto.randomUUID()
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "PRODUCT_V1" as const,
  uuid,
  name: "Test T-shirt",
  description: "A shirt for testing.",
  externalUrl: `https://example.com/${uuid}`,
  licenseUrl: `https://example.com/${uuid}/license`,
  image: "https://example.com/shirt.jpg",
  attributes: [
    { traitType: "Type", value: "Apparel" },
    { traitType: "Size", value: "M" },
  ],
  product: {
    uuid, version: 1,
    title: "Test T-shirt", description: "A shirt for testing.",
    productionInformation_brandName: "Your brand",
    details_offerCategory: "PHYSICAL",
    visuals_images: [{ url: "https://example.com/shirt.jpg", tag: "product" }],
  },
  seller: { defaultVersion: 1, name: "Your brand", contactLinks: [{ tag: "email", url: "mailto:hi@example.com" }] },
  shipping: { returnPeriod: "14" },
  exchangePolicy: { uuid: crypto.randomUUID(), version: 1, label: "fairExchangePolicy", template: "ipfs://Qm-template", sellerContactMethod: "email", disputeResolverContactMethod: "email" },
}
const metadataUri = await sdk.storeMetadata(metadata)

// 3. Create the offer
const tx2 = await sdk.createOffer({
  price: "1000000", // 1 USDC (6 decimals)
  sellerDeposit: "0",
  buyerCancelPenalty: "0",
  quantityAvailable: "10",
  exchangeToken: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia
  metadataUri,
  metadataHash: metadataUri.replace(/^ipfs:\/\//, ""),  // IPFS CID is the hash
  validFromDateInMS: Date.now(),
  validUntilDateInMS: Date.now() + 30 * 24 * 60 * 60 * 1000,
  voucherRedeemableFromDateInMS: Date.now(),
  voucherRedeemableUntilDateInMS: 0,
  voucherValidDurationInMS: 30 * 24 * 60 * 60 * 1000,
  disputePeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
  resolutionPeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
  collectionIndex: "0",
  disputeResolverId: "<your-dr-id>",                 // look up via sdk.getDisputeResolvers(); must support USDC
  agentId: "0",
  feeLimit: ethers.constants.MaxUint256.toString(),  // accept any fee
})
await tx2.wait()
console.log("Offer published.")
```

Run it:

```bash
SELLER_PRIVATE_KEY=0x... \
NEXT_PUBLIC_RPC_URL=https://sepolia.base.org \
IPFS_URL=https://your-pinning-endpoint \
pnpm tsx scripts/seed.ts
```

> Use an authenticated pinning endpoint for `IPFS_URL` (Pinata, web3.storage, your own Kubo node, …). The protocol default points at Infura, which now requires a project id.

## 4. Commit as a buyer

In a Next.js route handler:

```ts twoslash
// @noErrors
// src/app/api/commit/route.ts
import { NextResponse } from "next/server"
import { getSdkForSigner } from "@/lib/boson"

const USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"  // Base Sepolia USDC

export async function POST(req: Request) {
  const { offerId } = await req.json()
  const { sdk } = getSdkForSigner(process.env.BUYER_PRIVATE_KEY!)

  // Approve the ERC-20 token if needed. First arg is the TOKEN address.
  await (await sdk.approveExchangeToken(USDC, /* amount */ "1000000")).wait()

  // Commit — commitToOffer(offerId, overrides?); buyer is the signer.
  const tx = await sdk.commitToOffer(offerId)
  const receipt = await tx.wait()

  return NextResponse.json({ txHash: receipt.transactionHash })
}
```

## 5. Redeem the voucher

```ts twoslash
// @noErrors
import { getSdkForSigner } from "@/lib/boson"
const { sdk } = getSdkForSigner(process.env.BUYER_PRIVATE_KEY!)
const tx = await sdk.redeemVoucher(exchangeId)
await tx.wait()
```

## What just happened

You created an on-chain seller, pinned product metadata to IPFS, published an offer, had a buyer approve a token and commit (which mints a voucher rNFT to the buyer), then redeemed the voucher (which transitions the exchange from `COMMITTED` to `REDEEMED` and starts the dispute window).

## Common gotchas

- **`waitForGraphNodeIndexing` is mandatory** after writes if your next step reads from the subgraph. The subgraph lags 1–3 blocks. See [Concepts → Eventing & indexing](/concepts/eventing).
- **ERC-20 approval is per-token, not per-offer.** Approving 1 USDC means you can commit to 1 USDC of any USDC-priced offers — until your allowance runs out.
- **Validity dates are milliseconds, not seconds.** All `*InMS` params are ms since epoch. Double-check.
- **`feeLimit` is the max protocol fee you'll accept**, in token base units. Pass `MaxUint256` to accept any fee; passing `0` reverts with `TotalFeeExceedsLimit`.
- **`disputeResolverId` is env-specific** — it must exist on your chain and support the offer's `exchangeToken`. Look up the active set via `sdk.getDisputeResolvers()` before publishing.

## Next

- [Build → Sellers](/build/sellers) for production-grade seller flows.
- [Build → Buyers](/build/buyers) for buyer-side variations (atomic commit-and-redeem, dispute flows).
- [Concepts → Going to production](/concepts/production) before you swap `staging-84532-0` for `production-137-0`.

---

# Call Boson from Solidity in 10 minutes

URL: https://www.bosonprotocol.io/docs/quickstart/solidity

> Composing the Boson Diamond into your own smart contract with Foundry.

# Call Boson from Solidity in 10 minutes

What you'll build: a Solidity contract that commits to an offer on behalf of its caller. Useful primer for building custom orchestration or composing Boson into another protocol.

**Time**: 10 minutes. **Stack**: Foundry. **Network**: Base Sepolia.

## 1. Project

```bash
forge init boson-onchain
cd boson-onchain
forge install bosonprotocol/boson-protocol-contracts
```

## 2. The contract

```solidity
// src/Reseller.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IBosonExchangeCommit {
    function commitToOffer(address payable _buyer, uint256 _offerId) external payable;
}

contract Reseller {
    address public immutable diamond;

    constructor(address _diamond) {
        diamond = _diamond;
    }

    function passThroughCommit(uint256 offerId) external payable {
        IBosonExchangeCommit(diamond).commitToOffer{ value: msg.value }(payable(msg.sender), offerId);
    }
}
```

## 3. Find the Diamond address

Look up the Base Sepolia staging Diamond in [Networks → Contract addresses](/networks/addresses). For this quickstart:

```
DIAMOND=0x...   # Base Sepolia staging Diamond address from /networks/addresses
```

## 4. Deploy and call

```bash
forge create src/Reseller.sol:Reseller \
  --rpc-url $RPC \
  --private-key $PRIVATE_KEY \
  --constructor-args $DIAMOND

# Then call:
cast send $RESELLER_ADDR "passThroughCommit(uint256)" $OFFER_ID \
  --rpc-url $RPC \
  --private-key $PRIVATE_KEY \
  --value 1000000000000000000   # 1 ETH if it's a native-token offer
```

## Common gotchas

- **ERC-20 offers** require allowance on the Diamond before the inner `commitToOffer` is called. Pull the buyer's tokens to your contract first, approve the Diamond, then call.
- **The Diamond exposes _all_ facets at the same address.** Cast it to whichever interface you need.
- **NatSpec is the source of truth.** Browse the [facet sources](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/contracts/protocol/facets) for full docs.

## Next

- [Reference → Contracts → Diamond facets](/reference/contracts/facets) for the full callable surface.
- [Concepts → Architecture](/concepts/architecture) for how the Diamond is laid out.
- [Build → Sellers](/build/sellers) if you want to do this from TypeScript instead.

---

# Accept x402 escrow payments in 15 minutes

URL: https://www.bosonprotocol.io/docs/quickstart/x402-server

> Build an Express server that returns a 402 Payment Required with a Boson escrow option and settles via a facilitator.

# Accept x402 escrow payments in 15 minutes

What you'll build: an Express server that protects a resource behind an x402 Boson escrow payment challenge. Buyers sign a meta-transaction; a facilitator relays it to the Diamond; on success, the server returns the protected resource.

**Time**: 15 minutes. **Stack**: Node.js 20+, Express, `@bosonprotocol/x402-server-express`. **Network**: Base Sepolia.

:::warning
The x402 stack is **pre-release**. The API may change. Pin exact versions.
:::

## 1. Project

```bash
mkdir x402-seller && cd x402-seller
pnpm init
pnpm add express @bosonprotocol/x402-server-express @bosonprotocol/x402-core ethers@^5
pnpm add -D tsx typescript @types/node @types/express
```

## 2. Server

```ts twoslash
// @noErrors
// server.ts
import express from "express"
import { createX402bServerExpress } from "@bosonprotocol/x402-server-express"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.SELLER_PRIVATE_KEY!)

const app = express()

const x402 = createX402bServerExpress({
  network: "base-sepolia",
  chainId: 84532,
  escrow: {
    configId: "staging-84532-0",
    sellerId: "2",
    productUuid: "ec00f1a5-2c96-4d22-9d80-2a7c12345678",
  },
  signer: wallet,
  facilitator: {
    url: "https://facilitator.example.com", // your or a hosted facilitator
  },
})

app.get("/api/premium-data", x402.middleware(), async (req, res) => {
  // If we got here, payment is settled. The exchangeId is on req.x402.
  res.json({
    exchangeId: req.x402!.exchangeId,
    data: "Here is the thing you paid for.",
  })
})

app.listen(3000, () => console.log("x402 server listening on :3000"))
```

Run it:

```bash
SELLER_PRIVATE_KEY=0x... pnpm tsx server.ts
```

## 3. Make a paid request

From a buyer client:

```ts twoslash
// @noErrors
import { createX402bClientFetch } from "@bosonprotocol/x402-client-fetch"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.BUYER_PRIVATE_KEY!)
const fetchWithPayment = createX402bClientFetch({ signer: wallet })

const res = await fetchWithPayment("http://localhost:3000/api/premium-data")
console.log(await res.json())
```

The client:
1. Issues a plain `GET`.
2. Receives `402 Payment Required` with a Boson escrow option.
3. Signs a meta-transaction + token authorization.
4. Re-issues the `GET` with an `X-PAYMENT` header.
5. The server's middleware validates, the facilitator settles on-chain, the response is delivered.

## Common gotchas

- **Facilitator must be reachable from the server's network.** If the facilitator is in a private VPC, configure ingress.
- **Token-auth strategy mismatch.** Buyer and server must agree on at least one of: ERC-3009, EIP-2612, Permit2, plain approve. See [x402 → Token-auth strategies](/x402/token-auth).
- **State machine drift.** If you advance the exchange (e.g. atomic redeem) inside the middleware, declare it in `nextActions`. See [x402 → State-machine integration](/x402/state-machine).

## Next

- [Build with x402 → Overview](/x402) for production-grade integration.
- [Build with x402 → Facilitator](/x402/facilitator) for running your own.
- [Recipes → x402 buyer paying for a digital asset](/recipes/x402-buyer).
- [Recipes → x402 server email-fulfillment](/recipes/x402-email).

---

# Tooling overview

URL: https://www.bosonprotocol.io/docs/tooling

> Stack-by-stack comparison of Boson's developer surfaces — SDK, MCP, widgets, x402, Solidity, dApp, WooCommerce.

# Tooling overview

Boson exposes the same protocol through six developer surfaces. Pick whichever fits your stack; they all talk to the same on-chain Diamond and produce the same exchanges.

## Stack comparison

| Stack | Audience | Language | Maturity | Best for | Avoid if |
| --- | --- | --- | --- | --- | --- |
| [**Core SDK**](/tooling/core-sdk) | Backend / full-stack devs | TypeScript | Stable | Marketplaces, custom storefronts, server-side logic | You don't want to manage a wallet |
| [**React Kit**](/tooling/react-kit) | Frontend devs | TypeScript / React | Pre-release | Drop-in React components & hooks | You're not on React, or you need v1 stability |
| [**MCP stack**](/tooling/mcp) | AI / agent devs | Any (HTTP) | Stable | Autonomous buyer/seller agents, GOAT plugin users | You're not building an agent |
| [**Widgets**](/tooling/widgets) | Anyone with a webpage | HTML | Stable | Adding a buy button to an existing site | You need deep UI customization |
| [**x402 escrow**](/tooling/x402) | Service developers | TypeScript | Pre-release | Pay-per-request APIs, agent commerce over HTTP | You need long-term API stability |
| [**Solidity / contracts**](/tooling/contracts) | Smart-contract devs | Solidity | Stable | On-chain composition, custom orchestration | You don't want to write Solidity |
| [**The dApp**](/tooling/dapp) | Sellers / buyers | (none — UI) | Stable | Selling without writing code | You need automation |
| [**WooCommerce plugin**](/tooling/woocommerce) | WordPress merchants | (none — UI) | Stable | Adding Boson to an existing WordPress store | You're not on WooCommerce |

## What "stable" / "pre-release" means here

- **Stable** — the API surface is versioned; breaking changes are announced and migrations documented.
- **Pre-release** — the public API may change between minor versions. Pin exact dependency versions and watch the changelog.

## What every stack shares

No matter which surface you pick, you'll work with the same five cross-cutting concepts. Read these once:

1. [The Boson model](/concepts/model) — what offers, exchanges, and disputes are.
2. [Networks & ConfigIds](/concepts/networks-and-configids) — how to select a chain and environment.
3. [Signing & meta-transactions](/concepts/signing) — how transactions get signed and who pays gas.
4. [Eventing & indexing](/concepts/eventing) — how to watch for state changes (and why the subgraph lags).
5. [Going to production](/concepts/production) — operational checklist.

## How the stacks relate

```mermaid
flowchart TD
    Diamond["<b>On-chain Diamond</b><br/>EIP-2535 · 21 facets · multi-chain"]

    Diamond --> CoreSDK["<b>Core SDK</b><br/><code>@bosonprotocol/core-sdk</code>"]
    Diamond --> MCP["<b>MCP server</b><br/>~56 tools · hosted or self-hosted"]
    Diamond --> Contracts["<b>Contracts</b><br/>direct Solidity"]

    CoreSDK --> RK["React Kit<br/><i>hooks</i>"]
    CoreSDK --> Widgets["Widgets<br/><i>Commit · Redemption · Finance</i>"]
    CoreSDK --> X402["x402b stack<br/><i>server · client · facilitator</i>"]

    MCP --> GOAT["GOAT plugin<br/><i>Vercel AI · LangChain · Anthropic</i>"]
    MCP --> Client["BosonMCPClient<br/><i>typed TS client</i>"]
```

The dApp and WooCommerce plugin are end-user interfaces that sit on top of Core SDK + widgets — they're not separate stacks technically, but operationally they're a separate path for sellers who don't write code.

## Mixing stacks

Stacks compose. Common combinations:

- **Marketplace = Core SDK + Widgets**: SDK for backend listings, widgets for the buyer's commit flow.
- **Agent marketplace = MCP + Core SDK**: MCP for agent-driven trades, SDK for human marketplace operators monitoring exchanges.
- **API-as-a-service = x402 + Core SDK**: x402 for the HTTP-402 payment challenge, SDK for fulfillment hooks.

Read [Pick your integration](/pick-your-integration) for a quick decision tree.

---

# Solidity / contracts

URL: https://www.bosonprotocol.io/docs/tooling/contracts

> Direct on-chain integration with the Boson Diamond and its 21 handler facets.

# Solidity / contracts

The [`boson-protocol-contracts`](https://github.com/bosonprotocol/boson-protocol-contracts) repo holds the on-chain protocol: an [EIP-2535 Diamond](https://eips.ethereum.org/EIPS/eip-2535) proxy aggregating 21 handler facets.

You'd integrate at this layer if:
- You're composing Boson into another on-chain protocol.
- You want a custom orchestration that doesn't exist in the SDK or MCP.
- You're writing a custom dispute resolver or fee mutualizer.

For 95 % of integrations, the [Core SDK](/tooling/core-sdk) or [MCP](/tooling/mcp) is the right entry point.

## Get the addresses

The repo ships JSON address files per network at `addresses/{chainId}-{name}-{env}.json`. The new docs site auto-generates a table — see [Networks & addresses → Contract addresses](/networks/addresses).

## Get the ABIs

```bash
pnpm add @bosonprotocol/common @bosonprotocol/ethers-sdk
```

`@bosonprotocol/common` ships the merged Diamond ABI; `@bosonprotocol/ethers-sdk` ships TypeChain factories.

## Call from Solidity

```solidity
interface IBosonOfferHandler {
    function createOffer(
        BosonTypes.Offer calldata _offer,
        BosonTypes.OfferDates calldata _dates,
        BosonTypes.OfferDurations calldata _durations,
        uint256 _disputeResolverId,
        uint256 _agentId,
        uint256 _feeLimit
    ) external;
}

contract MyProtocol {
    IBosonOfferHandler immutable diamond;

    constructor(address _diamond) {
        diamond = IBosonOfferHandler(_diamond);
    }

    function listMyThing(/* … */) external {
        diamond.createOffer(/* … */);
    }
}
```

The Diamond exposes _all_ 21 facets' functions at the same address. Cast it to whichever interface you need.

## Reference

- [Reference → Contracts → Diamond facets](/reference/contracts/facets)
- [Reference → Contracts → Events](/reference/contracts/events)
- [Reference → Contracts → Custom errors](/reference/contracts/errors)
- [Reference → Contracts → Structs](/reference/contracts/structs)

## Next

- [Quickstart → Call Boson from Solidity](/quickstart/solidity) — 10-minute walk-through.
- [Concepts → Architecture: the Diamond](/concepts/architecture).

---

# Core SDK

URL: https://www.bosonprotocol.io/docs/tooling/core-sdk

> The @bosonprotocol/core-sdk TypeScript SDK — the primary developer entry point for human-facing apps.

# Core SDK

`@bosonprotocol/core-sdk` is the TypeScript SDK most teams should reach for first. It's a thin, mixin-based wrapper over the on-chain Diamond and the Boson subgraph. Stable, multi-chain, server-and-browser compatible.

## Install

:::code-group
```bash [pnpm]
pnpm add @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk ethers@^5
```
```bash [npm]
npm install @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk ethers@^5
```
```bash [yarn]
yarn add @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk ethers@^5
```
:::

The SDK is wallet-library-agnostic. Use `@bosonprotocol/ethers-sdk` for ethers v5 (the default), or bridge a viem `WalletClient` via the helper in `@bosonprotocol/x402b`'s `walletClientToWeb3LibAdapter()`.

## Hello world

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { ethers } from "ethers"

const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL)
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

const sdk = CoreSDK.fromDefaultConfig({
  web3Lib: new EthersAdapter(provider, wallet),
  envName: "staging",
  configId: "staging-84532-0", // Base Sepolia (testnet)
})

const offers = await sdk.getOffers({ first: 10 })
console.log(offers)
```

Everything beyond this — creating sellers, publishing offers, committing to offers, redeeming, disputes — is documented per-task in [Build](/build/sellers).

## What's in the box

The `CoreSDK` class aggregates a set of **mixins**, each handling one domain. You don't instantiate them separately — they're all methods on `sdk`.

| Mixin | Reference | What it covers |
| --- | --- | --- |
| Accounts | [→](/reference/core-sdk/accounts) | `createSeller`, `createBuyer`, `createDisputeResolver`, role management |
| Offers | [→](/reference/core-sdk/offers) | `createOffer`, `voidOffer`, querying offers |
| Exchanges | [→](/reference/core-sdk/exchanges) | `commitToOffer`, `redeemVoucher`, `completeExchange`, `cancelVoucher` |
| Disputes | [→](/reference/core-sdk/disputes) | `raiseDispute`, `resolveDispute`, `escalateDispute`, `decideDispute` |
| Funds | [→](/reference/core-sdk/funds) | `depositFunds`, `withdrawFunds`, getting balances |
| MetaTx | [→](/reference/core-sdk/meta-tx) | EIP-712 signing helpers, Biconomy relay support |
| Orchestration | [→](/reference/core-sdk/orchestration) | Atomic combos like `createOfferAndCommit`, `createOfferCommitAndRedeem` |
| Groups | [→](/reference/core-sdk/groups) | Token-gating conditions |
| Marketplace | [→](/reference/core-sdk/marketplace) | Subgraph-backed marketplace queries |
| Search | [→](/reference/core-sdk/search) | Full-text and faceted search over offers |
| ERC20 / 721 / 1155 | [→](/reference/core-sdk/erc-mixins) | Token approvals, transfers, and balance checks used by token-gating |

## When to use the SDK vs. something else

- **You're writing server-side code or a custom UI** → SDK.
- **You're writing a React frontend and want hooks** → SDK *plus* [React Kit](/tooling/react-kit).
- **You want a drop-in commit button** → [Embeddable widgets](/tooling/widgets) (no SDK needed).
- **You're building an autonomous agent** → [MCP stack](/tooling/mcp). You _can_ use the SDK from an agent, but MCP gives you a typed tool registry for free.

## Versioning

Follow the [`core-components`](https://github.com/bosonprotocol/core-components) repo releases. The SDK and the Diamond are versioned in lockstep through `configId` indexes; if the Diamond gets a new index, the SDK release notes will say so. Pin exact versions in production.

## Next

- Pick a [Quickstart](/quickstart/marketplace) for an end-to-end walk-through.
- Open the [Core SDK reference](/reference/core-sdk/core-sdk) for full type signatures.
- Read [Signing & meta-transactions](/concepts/signing) before going to production.

---

# The Boson dApp

URL: https://www.bosonprotocol.io/docs/tooling/dapp

> The hosted web app — sell, buy, and manage funds without writing any code.

# The Boson dApp

The Boson dApp is a hosted web interface that wraps the protocol for users who don't write code. Connect a wallet and you can create a seller account, publish offers, commit to existing offers, redeem, dispute, and withdraw — all through a UI.

**For sellers**, the dApp is the no-code path to listing physical or digital products. See [Build / Sellers / Sell via the Boson dApp](/build/sellers/dapp).

**For buyers**, the dApp is the simplest way to browse and purchase. See [Build / Buyers / Buy via the Boson dApp](/build/buyers/dapp).

## When to choose the dApp

- You're a seller who wants to test-list a product without writing code.
- You're a marketplace operator who wants to point buyers at a "Buy on Boson" link rather than build your own UI.
- You're prototyping a flow and want to confirm protocol behavior before integrating an SDK.

## When _not_ to choose the dApp

- You need to automate listings or commits at scale → [Core SDK](/tooling/core-sdk) or [MCP](/tooling/mcp).
- You want a buy button on your own site → [Embeddable widgets](/tooling/widgets).
- You sell through WordPress → [WooCommerce plugin](/tooling/woocommerce).

---

# MCP / agent stack

URL: https://www.bosonprotocol.io/docs/tooling/mcp

> The Boson MCP server, BosonMCPClient, and the GOAT SDK plugin — three ways to give an AI agent access to Boson.

# MCP / agent stack

The `agentic-commerce` repo packages Boson as a [Model Context Protocol](https://modelcontextprotocol.io) server with ~56 tools, plus two ways to consume it: a typed TypeScript client and a [GOAT SDK](https://github.com/goat-sdk/goat) plugin.

## Hosted endpoints

You don't have to run anything to start.

| Env | URL |
| --- | --- |
| Staging | `https://mcp-staging.bosonprotocol.io/mcp` |
| Production | `https://mcp.bosonprotocol.io/mcp` |

To run locally (stdio or HTTP):

```bash
npx @bosonprotocol/agentic-commerce boson-mcp-server
```

## Three integration paths

### 1. GOAT SDK plugin (recommended for Vercel AI / LangChain / Claude)

```ts twoslash
// @noErrors
import { bosonProtocolPlugin } from "@bosonprotocol/agentic-commerce"
import { getOnChainTools } from "@goat-sdk/adapter-vercel-ai"
import { viem } from "@goat-sdk/wallet-viem"
import { walletClient } from "./wallet"

const tools = await getOnChainTools({
  wallet: viem(walletClient),
  plugins: [
    bosonProtocolPlugin({
      url: "https://mcp-staging.bosonprotocol.io/mcp",
    }),
  ],
})
// `tools` now contains all 56 Boson tools, typed and ready to register with the model.
```

The plugin handles MCP transport, signs transactions through the wallet you pass in, and broadcasts. Fewest moving parts.

### 2. BosonMCPClient (typed TS client)

```ts twoslash
// @noErrors
import { BosonMCPClient } from "@bosonprotocol/agentic-commerce/boson"

const client = new BosonMCPClient()
await client.connectToServer(
  "https://mcp-staging.bosonprotocol.io/mcp",
)

const unsignedTx = await client.createSeller({
  configId: "staging-84532-0",
  signerAddress: wallet.address,
  // ...
})
// You sign and broadcast yourself, via send_signed_transaction or your own wallet.
```

Use this when you want full control over signing and broadcasting — e.g. your wallet is in an HSM, in MPC custody, or behind a session-key manager. See [Build for AI agents → Wallet patterns](/agents/wallets).

### 3. Raw MCP over HTTP

Any MCP-compliant client works (Claude Desktop, Cline, Cursor, etc.). Point it at the hosted URL and the tools appear in the model's tool registry. Signing is your responsibility.

## What's in the tool catalogue

| Category | Tools | Count |
| --- | --- | --- |
| Seller & buyer | `create_seller`, `update_seller`, `create_buyer`, `get_sellers`, `get_sellers_by_address`, `get_dispute_resolvers` | 6 |
| Offer | `create_offer`, `create_offer_with_condition`, `sign_full_offer`, `create_offer_and_commit`, `void_offer` (+ batch + non-listed), `get_offers`, `get_all_products_with_not_voided_variants`, metadata helpers, `render_contractual_agreement` | 13 |
| Exchange | `get_exchanges`, `approve_exchange_token`, `commit_to_offer`, `commit_to_buyer_offer`, `complete_exchange`, `cancel_voucher`, `revoke_voucher`, `redeem_voucher` | 9 |
| Dispute | raise / resolve / retract / escalate / decide / refuse / expire (+ batch) / extend / create-proposal / read | 13 |
| Funds & meta-tx | `deposit_funds`, `withdraw_funds`, `get_funds`, `send_meta_transaction`, `send_native_meta_transaction`, `send_forwarded_meta_transaction`, `send_signed_transaction` | 7 |
| Agent registry | `register_agent`, `get_registered_agents` | 2 |
| Config | `get_config_ids`, `get_supported_tokens` | 2 |

Full schemas and examples are in [Reference → MCP tools](/reference/mcp-tools).

## Wallet management

The MCP server **never sees private keys**. State-changing tools return _unsigned_ transactions; your client signs them. See [Build for AI agents → The 3-step signing pattern](/agents/signing) for the canonical flow.

## High-value asset module (Fermion)

A separate MCP server exposes tools for premium / fractionalized assets, with extra roles (verifier, custodian). See [Build for AI agents → High-value asset module](/agents/fermion).

## Next

- [Quickstart → Buy with an AI agent](/quickstart/ai-agent-buyer) — 5-minute hello-world.
- [Build for AI agents](/agents) — patterns for autonomous buyer/seller agents.
- [Reference → MCP tools](/reference/mcp-tools) — every tool's schema, errors, and idempotency notes.

---

# React Kit

URL: https://www.bosonprotocol.io/docs/tooling/react-kit

> Pre-release React components and hooks for building Boson-powered frontends.

# React Kit

`@bosonprotocol/react-kit` ships React components and hooks layered on top of the [Core SDK](/tooling/core-sdk). It's also the engine behind the [embeddable widgets](/tooling/widgets) — the widgets are deployed React Kit apps.

:::warning
**Pre-release.** The hook surface is still settling. Pin exact versions and watch the changelog. For long-term-stable surfaces, prefer raw Core SDK + your own React glue.
:::

## Install

```bash
pnpm add @bosonprotocol/react-kit @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk react@^18 react-dom@^18
```

## What's in the box

- **Provider** — wraps your app and constructs a `CoreSDK` from a `configId`.
- **Hooks** — `useOffers`, `useExchanges`, `useFunds`, etc. They wrap subgraph queries with React Query.
- **Components** — `<CommitButton />`, `<RedemptionFlow />`, `<FinanceCard />`. Higher-level than raw hooks; less flexible.

## When to use React Kit vs. the SDK directly

- **Use React Kit** when you want pre-built UI for the common buyer flow.
- **Use Core SDK + your own React** when your UI is custom and you want full control.

## Versioning

Follow [`core-components`](https://github.com/bosonprotocol/core-components) — React Kit ships alongside the SDK.

## Reference

See [Reference → React Kit](/reference/react-kit) for the component and hook catalogue.

---

# Embeddable widgets

URL: https://www.bosonprotocol.io/docs/tooling/widgets

> Drop-in UI for committing, redeeming, and managing funds — the lowest-effort way to add Boson to an existing site.

# Embeddable widgets

Three pre-built widgets handle the three most common buyer-side flows. Each is a hosted React app you can embed via `<script>` + a target element, an `<iframe>`, or a [Zoid](https://github.com/krakenjs/zoid) cross-origin portal.

| Widget | Use when | URL |
| --- | --- | --- |
| **Commit Widget** | Buyer accepts an offer and pays | [`/widgets/commit`](/widgets/commit) |
| **Redemption Widget** | Buyer redeems, cancels, or disputes a voucher | [`/widgets/redemption`](/widgets/redemption) |
| **Finance Widget** | Seller or buyer manages on-chain funds | [`/widgets/finance`](/widgets/finance) |

## Quick embed

```html
<!-- Loads the widget loader once -->
<script src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js" async></script>

<!-- Place a commit button anywhere -->
<button
  id="boson-commit"
  data-config-id="production-137-0"
  data-seller-id="2"
  data-product-uuid="…">
  Buy now
</button>
```

For full options, see [Widgets → Embedding methods](/widgets/embedding) and [Widgets → Configuration](/widgets/configuration).

## Hosted at

`https://widgets.bosonprotocol.io/` — the canonical deployment.

## Versioning

Widgets are continuously deployed from the `widgets` repo and follow the React Kit version. The script tag always points at the latest stable build; pin a SHA-stamped URL if you need version stability.

---

# WooCommerce plugin

URL: https://www.bosonprotocol.io/docs/tooling/woocommerce

> Sell through your existing WordPress / WooCommerce store with Boson Protocol escrow.

# WooCommerce plugin

The Boson for WooCommerce plugin turns an existing WooCommerce storefront into a Boson seller. Products listed in WooCommerce are mirrored as Boson offers; buyers commit through the Boson widget at checkout; fulfillment flows back into your existing WooCommerce order pipeline.

**When to use**: you already have a WooCommerce store and want to add tokenized-commitment / escrow flows without rebuilding your storefront.

**Detailed walk-through**: [Build / Sellers / Sell via WooCommerce](/build/sellers/woocommerce).

**Recipe**: [Recipes → Sell via WooCommerce](/recipes/woocommerce).

---

# x402 escrow stack

URL: https://www.bosonprotocol.io/docs/tooling/x402

> Boson's HTTP-402 escrow stack — pay for an HTTP resource and have funds held in escrow until delivery.

# x402 escrow stack

`x402b` extends the [x402](https://x402.org) standard (in-band HTTP-402 payments) with non-custodial escrow on the Boson Diamond. A buyer requests a resource, gets a `402 Payment Required` with a Boson escrow option, signs a meta-transaction, and the facilitator settles it on-chain. Funds release on redemption or dispute resolution.

:::warning
**Pre-release.** The `x402b` packages are pre-1.0 and the API surface will change. Pin exact versions.
:::

## Packages

| Package | Role | Reference |
| --- | --- | --- |
| `x402-core` | Schemas, EIP-712 builders, state machine | [→](/reference/x402/x402-core) |
| `x402-evm` | Calldata builders for the two flows (deferred / atomic) | [→](/reference/x402/x402-evm) |
| `x402-server` | Resource-server SDK (framework-agnostic) | [→](/reference/x402/x402-server) |
| `x402-server-express` | Express adapter | (in package) |
| `x402-client` | Buyer-side SDK (framework-agnostic) | [→](/reference/x402/x402-client) |
| `x402-client-fetch` | Fetch API adapter | (in package) |
| `x402-facilitator` | Reference relayer library | [→](/reference/x402/x402-facilitator) |
| `x402-facilitator-express` | Express adapter | (in package) |
| `x402-fulfillment` | Pluggable fulfillment channels (inline · email · XMTP · webhook · IPFS) | [→](/reference/x402/x402-fulfillment) |
| `x402-actions` | State machine + `nextActions` envelope | [→](/reference/x402/x402-actions) |

## Three actors

```mermaid
sequenceDiagram
    autonumber
    participant Buyer
    participant Server as Seller server<br/>(x402-server)
    participant Client as Buyer client<br/>(x402-client)
    participant Facilitator as Facilitator<br/>(x402-facilitator)
    participant Chain as Boson Diamond

    Buyer->>Server: HTTP request
    Server-->>Buyer: 402 Payment Required<br/>+ escrow option
    Buyer->>Client: pass challenge
    Note over Client: signs meta-tx<br/>+ token-auth
    Client->>Facilitator: signed X-PAYMENT
    Facilitator->>Chain: commit (+ optional atomic redeem)
    Chain-->>Facilitator: receipt
    Facilitator-->>Server: settled
    Server-->>Buyer: 200 OK<br/>+ delivery via fulfillment channel
```

## When to use x402

- You sell access to an HTTP resource (API, file, model inference).
- The buyer is an AI agent that needs in-band payment, not OAuth + Stripe.
- You want non-custodial escrow without writing your own contracts.

If you're selling physical goods, use the [Core SDK](/tooling/core-sdk) directly. If you're selling digital goods through a marketplace, use the [SDK](/tooling/core-sdk) or [MCP](/tooling/mcp).

## Next

- [Build with x402 → Overview](/x402) for the full integration walkthrough.
- [Quickstart → Accept x402 escrow payments](/quickstart/x402-server) for a 15-minute setup.

---

# Architecture — the Diamond

URL: https://www.bosonprotocol.io/docs/concepts/architecture

> How the on-chain protocol is laid out — EIP-2535 Diamond with 21 handler facets.

# Architecture — the Diamond

The Boson on-chain protocol is a single contract: a [Diamond](https://eips.ethereum.org/EIPS/eip-2535) (EIP-2535) proxy that delegates to 21 _handler facets_, each implementing one domain. All write paths go through this single address.

## Why a Diamond

- **One address per chain** — easier to integrate, easier to authorize, easier to audit.
- **Upgradeable per-facet** — protocol can ship a fix to dispute logic without touching offer logic.
- **No 24 KB contract-size limit** — facets are independent contracts; the Diamond is a router.
- **Single storage namespace** — all facets share the protocol storage, so cross-domain reads are cheap.

## The 21 facets

| Facet | Domain |
| --- | --- |
| `OfferHandlerFacet` | Create / void offers; offer queries |
| `ExchangeCommitFacet` | `commitToOffer`, including buyer-initiated |
| `ExchangeHandlerFacet` | Redeem, complete, cancel, revoke vouchers |
| `DisputeHandlerFacet` | Raise / resolve / escalate / decide disputes |
| `FundsHandlerFacet` | Deposit / withdraw treasuries |
| `AccountHandlerFacet` | High-level entity creation |
| `SellerHandlerFacet` | Seller-specific config, royalties, allowlists |
| `BuyerHandlerFacet` | Buyer queries |
| `DisputeResolverHandlerFacet` | DR registration, fees, allowlists |
| `AgentHandlerFacet` | Protocol agents |
| `GroupHandlerFacet` | Token-gating conditions |
| `BundleHandlerFacet` | Multi-item bundles |
| `TwinHandlerFacet` | Conditional twin items (rare) |
| `MetaTransactionsHandlerFacet` | EIP-712 envelopes, token-auth |
| `OrchestrationHandlerFacet1` / `2` | Atomic combos (`createOfferAndCommit`, `createOfferCommitAndRedeem`) |
| `PriceDiscoveryHandlerFacet` | Auction / discovery pricing |
| `SequentialCommitHandlerFacet` | Batch / expiration semantics |
| `ConfigHandlerFacet` | Protocol params, fees, pause regions |
| `PauseHandlerFacet` | Region-based pause control |
| `ProtocolInitializationHandlerFacet` | One-time setup |

Full reference: [Reference → Contracts → Diamond facets](/reference/contracts/facets).

## Read paths

For reads, prefer the **subgraph** (see [Eventing & indexing](/concepts/eventing)). The Diamond exposes getters too, but reading dozens of fields is expensive without batching.

## Surrounding contracts

The Diamond does most of the work, but a few helpers ship alongside:

- **Voucher (rNFT) ERC-721** — an individual collection contract used by sellers; minted on commit, burned on redemption. A seller can have multiple voucher contracts.
- **Permit2** — the Uniswap permit-as-a-service contract, used by token-auth meta-tx.
- **Forwarder** — meta-tx forwarder for the Biconomy relay path.
- **PriceDiscoveryClient** — adapter contract for discovery-based price flows.

Addresses for all of these are in the per-chain JSON files; see [Networks → Contract addresses](/networks/addresses).

## Storage

All facets share a single ERC-7201-style storage namespace, with a per-domain struct: `protocolEntities`, `protocolLookups`, `protocolCounters`, `protocolStatus`, etc. Defined in `BosonTypes.sol` + `ProtocolLib.sol`.

You don't read storage directly — use the appropriate getter facet — but knowing the layout helps you decode events.

## Upgrades

Per-facet upgrades are governed by a multisig. Upgrade scripts live in [`boson-protocol-contracts/scripts/upgrade-facets.js`](https://github.com/bosonprotocol/boson-protocol-contracts). Each upgrade gets a new `configId` only on _breaking_ changes; routine logic changes preserve the existing `configId`.

## Common footguns

- **Don't hard-code a facet's contract address.** All facets are reachable via the Diamond; the facet addresses change on upgrade.
- **Don't decode events from a single-facet ABI.** Use the merged ABI in `@bosonprotocol/common`.
- **Pause regions matter.** During an incident, individual regions (offers, exchanges, disputes) can be paused independently. Read `protocol.pausedRegions()` before assuming a call will succeed.

## Next

- [Reference → Contracts → Diamond facets](/reference/contracts/facets).
- [Tooling → Solidity / contracts](/tooling/contracts).
- [Quickstart → Call Boson from Solidity](/quickstart/solidity).

---

# Dispute state machine

URL: https://www.bosonprotocol.io/docs/concepts/dispute-state-machine

> Every state a dispute can be in once raised, with the resolution and escalation paths.

# Dispute state machine

A dispute is the side state machine that runs when an [exchange](/concepts/exchange-state-machine) is contested. Once raised, the parent exchange sits in `DISPUTED` until the dispute terminates.

```mermaid
stateDiagram-v2
    [*] --> RESOLVING: raiseDispute (buyer)

    state retractJoin <<choice>>
    state resolveJoin <<choice>>

    RESOLVING --> retractJoin
    ESCALATED --> retractJoin 
    retractJoin --> RETRACTED: retractDispute (buyer)

    RESOLVING --> resolveJoin 
    ESCALATED --> resolveJoin
    resolveJoin --> RESOLVED: resolveDispute (mutual, signed by both)

    RESOLVING --> ESCALATED: escalateDispute (buyer, during resolution window)
    RESOLVING --> EXPIRED: expireDispute (anyone, after resolution window)

    ESCALATED --> DECIDED: decideDispute (DR, binding split)
    ESCALATED --> REFUSED: refuseEscalatedDispute (DR refuses to arbitrate)
    ESCALATED --> REFUSED: expireEscalatedDispute (anyone, after escalation window)

    state Terminal {
      direction LR
      RETRACTED
      RESOLVED
      DECIDED
      REFUSED
      EXPIRED
    }
```

## State table

| State | Who transitions out | To | Action |
| --- | --- | --- | --- |
| `RESOLVING` | Buyer | `RETRACTED` | `retractDispute(exchangeId)` — buyer gives up |
| `RESOLVING` | Both, mutual EIP-712 | `RESOLVED` | `resolveDispute(exchangeId, buyerPercent, sigB, sigS)` |
| `RESOLVING` | Buyer (after window) | `ESCALATED` | `escalateDispute(exchangeId)` |
| `RESOLVING` | Anyone | `EXPIRED` | `expireDispute(exchangeId)` |
| `ESCALATED` | DR | `DECIDED` | `decideDispute(exchangeId, buyerPercent)` |
| `ESCALATED` | DR | `REFUSED` | `refuseEscalatedDispute(exchangeId)` |
| `ESCALATED` | Buyer | `RETRACTED` | `retractDispute(exchangeId)` — buyer gives up |
| `ESCALATED` | Both, mutual EIP-712 | `RESOLVED` | `resolveDispute(exchangeId, buyerPercent, sigB, sigS)` |
| `ESCALATED` | Anyone | `REFUSED` | `expireEscalatedDispute(exchangeId)` |

## Funds movement on terminal state

| Terminal | Buyer gets | Seller gets | DR gets |
| --- | --- | --- | --- |
| `RETRACTED` | nothing (gives up) | price + their deposit back | nothing |
| `RESOLVED` | `buyerPercent` of escrow | rest | nothing |
| `DECIDED` | `buyerPercent` of escrow | rest | their fee |
| `REFUSED` | full escrow (price + escalation fee) | their deposit back | nothing |
| `EXPIRED` (from `RESOLVING`) | nothing | price + their deposit | nothing |

## Where to look in code

| Surface | Where |
| --- | --- |
| Contracts | [`DisputeHandlerFacet`](/reference/contracts/facets) |
| Core SDK | [Disputes mixin](/reference/core-sdk/disputes) |
| MCP | `raise_dispute`, `retract_dispute`, `resolve_dispute`, `escalate_dispute`, `decide_dispute`, `refuse_escalated_dispute`, `expire_dispute`(`_batch`), `expire_escalated_dispute`, `extend_dispute_timeout`, `create_dispute_resolution_proposal` |

## Common footguns

- **Mutual resolution requires signatures from _both_ buyer and seller.** EIP-712 typed-data. See [Signing & meta-transactions](/concepts/signing).
- **DR fees come out of the escrow on `DECIDED`, but are refunded to the buyer on `REFUSED`.** Plan UX accordingly.
- **The dispute machine doesn't reset the exchange.** Once a dispute terminates, the parent exchange goes to `COMPLETED` (or stays in a terminal state mirroring the dispute outcome) — read both states when reconstructing history.

## Next

- [Build → Buyers → Raise a dispute](/build/buyers/raise-dispute).
- [Build → Dispute Resolvers](/build/dispute-resolvers).
- [Recipes → Mutual dispute resolution](/recipes/mutual-dispute).

---

# Eventing & indexing

URL: https://www.bosonprotocol.io/docs/concepts/eventing

> How to watch for state changes — subgraph vs RPC logs vs webhooks — and why the subgraph lags.

# Eventing & indexing

Watching for on-chain state changes is the second-most-common task after creating them. Boson exposes three eventing surfaces; pick by latency tolerance and throughput.

## The three surfaces

| Surface | Latency | Throughput | Best for |
| --- | --- | --- | --- |
| **RPC logs** (`eth_getLogs`, WebSocket) | 0–1 block | Limited by node | Real-time triggers, single-app dashboards |
| **Subgraph** (The Graph) | **1–3 blocks** | Unlimited GraphQL | Marketplaces, listings, history queries |
| **Your own webhook server** | Same as input (RPC or subgraph) | Whatever you build | Persisting orders to your CRM / fulfillment system |

The subgraph is convenient (typed GraphQL, joins across offers/exchanges/disputes), but **it lags**. Plan for it.

## The subgraph indexing lag

After a transaction is mined, the Boson subgraph waits for the indexer to process it — typically 1–3 blocks. If you commit at block N and immediately read `getExchanges()`, you may get nothing for blocks N..N+3.

**Don't poll the subgraph in a tight loop.** Use the SDK helper:

```ts twoslash
// @noErrors
const tx = await sdk.commitToOffer(buyer, offerId)
const receipt = await tx.wait()

await sdk.waitForGraphNodeIndexing(receipt.blockNumber)

const exchanges = await sdk.getExchanges({ where: { buyer } })
```

`waitForGraphNodeIndexing(blockNumber)` polls the subgraph's `_meta` until the indexed block ≥ `blockNumber`. Default timeout is ~30 seconds.

Inside an agent loop, treat this as **mandatory**. See [Build for AI agents → Idempotency & retry](/agents/idempotency) and [Troubleshooting → Subgraph indexing lag](/troubleshooting/indexing-lag).

## Reading from RPC logs

For zero-lag, listen to events directly:

```ts twoslash
// @noErrors
import { ethers } from "ethers"

const diamond = new ethers.Contract(diamondAddress, diamondAbi, provider)

diamond.on("BuyerCommitted", (offerId, buyerId, exchangeId, exchangeStruct, /* … */) => {
  // … immediately persist or react
})
```

The Diamond emits events from every facet at the same contract address. Use the merged ABI from `@bosonprotocol/common`.

## Critical events

| Event | Emitted by | Fires on |
| --- | --- | --- |
| `OfferCreated` | `OfferHandlerFacet` | `createOffer` |
| `OfferVoided` | `OfferHandlerFacet` | `voidOffer` |
| `BuyerCommitted` | `ExchangeCommitFacet` | `commitToOffer` (creates an exchange) |
| `VoucherRedeemed` | `ExchangeHandlerFacet` | `redeemVoucher` |
| `ExchangeCompleted` | `ExchangeHandlerFacet` | `completeExchange` |
| `VoucherCanceled` | `ExchangeHandlerFacet` | `cancelVoucher` (buyer) |
| `VoucherRevoked` | `ExchangeHandlerFacet` | `revokeVoucher` (seller) |
| `DisputeRaised` | `DisputeHandlerFacet` | `raiseDispute` |
| `DisputeResolved` | `DisputeHandlerFacet` | `resolveDispute` |
| `DisputeDecided` | `DisputeHandlerFacet` | `decideDispute` |
| `FundsDeposited` | `FundsHandlerFacet` | `depositFunds` |
| `FundsWithdrawn` | `FundsHandlerFacet` | `withdrawFunds` |

Full list at [Reference → Contracts → Events](/reference/contracts/events).

## Building a webhook server

Run an event listener that posts to your backend. See [Recipes → Webhook server for state changes](/recipes/webhook-server) for a complete reference implementation.

The common shape:

::::steps

### RPC subscription _or_ subgraph poll

Pull events from a chain RPC (`eth_subscribe` / log filter) or by polling the subgraph.

### Filter and dedupe

Match the event types you care about; remember the last block + log index so you don't fire twice if the source replays.

### HTTP POST to your handler

Deliver the event to your backend, with retries on non-2xx responses.

::::

## Reorg handling

Every chain Boson runs on can reorg. Defensive practices:

- Wait **2–3 confirmations** before treating an event as final on Polygon / Base / Optimism / Arbitrum; **12+** on Mainnet.
- Make your webhook handler **idempotent** — keyed on `(txHash, logIndex)` or `(exchangeId, newState)`.
- For high-stakes actions, re-read state from RPC before acting (don't trust the event payload alone).

## Common footguns

- **Subgraph "missing data" right after a write.** Indexing lag. Use `waitForGraphNodeIndexing`.
- **Polygon RPC rate limits.** Free-tier RPCs throttle. Use a paid provider for production.
- **Event ABIs from old versions.** If you read events from a Diamond before an upgrade and decode with a post-upgrade ABI, field order can shift. Pin the ABI to the version you indexed at.

## Where to look in code

- [Reference → Contracts → Events](/reference/contracts/events)
- [Reference → Core SDK → Marketplace mixin](/reference/core-sdk/marketplace) — subgraph queries
- [Reference → Subgraph queries](/reference/subgraph)

## Next

- [Build → Marketplace operators → Webhooks & events](/build/marketplace/webhooks).
- [Troubleshooting → Subgraph indexing lag](/troubleshooting/indexing-lag).
- [Recipes → Webhook server](/recipes/webhook-server).

---

# Exchange state machine

URL: https://www.bosonprotocol.io/docs/concepts/exchange-state-machine

> Every state an exchange can be in, who can transition it, and which tool / SDK method / facet to call.

# Exchange state machine

Every commitment to an offer becomes an **exchange** with a state. The state machine is small, but the transitions are the protocol's contract surface.

```mermaid
stateDiagram-v2
    [*] --> COMMITTED: commitToOffer (buyer)
    COMMITTED --> REDEEMED: redeemVoucher (buyer)
    COMMITTED --> CANCELLED: cancelVoucher (buyer, with penalty)
    COMMITTED --> REVOKED: revokeVoucher (seller, before redeem)
    COMMITTED --> EXPIRED: expireVoucher (anyone, after redemption window)
    REDEEMED --> COMPLETED: completeExchange (anyone, after dispute window)
    REDEEMED --> DISPUTED: raiseDispute (buyer, within dispute window)
    DISPUTED --> [*]: (see Dispute state machine)
    
    state Terminal {
      direction LR
      COMPLETED
      CANCELLED
      REVOKED
      EXPIRED
    }
```

## State table

| State | Who can transition out | To | Action | Funds movement |
| --- | --- | --- | --- | --- |
| `COMMITTED` | Buyer | `REDEEMED` | `redeemVoucher(exchangeId)` | none (yet) |
| `COMMITTED` | Buyer | `CANCELLED` | `cancelVoucher(exchangeId)` | buyer loses `buyerCancelPenalty`, gets rest back |
| `COMMITTED` | Seller | `REVOKED` | `revokeVoucher(exchangeId)` | seller loses `sellerDeposit` to buyer |
| `COMMITTED` | Anyone | `EXPIRED` | `expireVoucher(exchangeId)` | buyer loses `buyerCancelPenalty`, gets rest back |
| `REDEEMED` | Anyone | `COMPLETED` | `completeExchange(exchangeId)` after dispute window | seller treasury receives price |
| `REDEEMED` | Buyer | `DISPUTED` | `raiseDispute(exchangeId)` within dispute window | escrow held pending resolution |

## What "anyone" means

`completeExchange` and the auto-`EXPIRED` transitions can be triggered by any wallet. Sellers typically batch-call them via `complete_exchange` to release earnings. See [Build → Sellers → Manage funds](/build/sellers/manage-funds).

## Windows

Three time windows govern the state machine. All set on the offer at creation:

- **Validity window** (`validFromDate`–`validUntilDate`) — when buyers can commit.
- **Voucher window** (`voucherRedeemable{From,Until,ValidDuration}`) — when the buyer can redeem.
- **Dispute window** — fixed `disputeDuration` after redemption.

A buyer who doesn't redeem before the voucher window closes loses the price; the seller still loses `sellerDeposit`. This protects the buyer against silent seller absence.

## Where to look in code

| Surface | Where |
| --- | --- |
| Contracts | [`ExchangeCommitFacet`, `ExchangeHandlerFacet`, `DisputeHandlerFacet`](/reference/contracts/facets) |
| Core SDK | [Exchanges mixin](/reference/core-sdk/exchanges), [Disputes mixin](/reference/core-sdk/disputes) |
| MCP | `commit_to_offer`, `redeem_voucher`, `cancel_voucher`, `revoke_voucher`, `complete_exchange`, `raise_dispute` — see [Reference → MCP tools](/reference/mcp-tools) |

## Common footguns

- **Don't read the new state until the subgraph indexes it.** See [Eventing & indexing](/concepts/eventing).
- **The `EXPIRED` transition is implicit.** No event fires when a voucher silently expires; you must check `voucherRedeemableUntilDate` against `block.timestamp`. The subgraph synthesizes the state for you.
- **`cancelVoucher` is buyer-initiated; `revokeVoucher` is seller-initiated.** Different functions; different penalties.

## Next

- [Dispute state machine](/concepts/dispute-state-machine) — what happens after a dispute is raised.
- [Offer lifecycle](/concepts/offer-lifecycle) — the parent entity's state.
- [Build → Sellers → Handle redemption / deliver](/build/sellers/handle-redemption) for the fulfillment side.

---

# Fulfillment channels

URL: https://www.bosonprotocol.io/docs/concepts/fulfillment

> How sellers deliver after a buyer redeems — inline, email, XMTP, webhook, IPFS pointer.

# Fulfillment channels

Boson is a commitment / escrow protocol — it doesn't deliver the goods for you. What it does provide is a state machine that says _when_ delivery is owed (after `REDEEMED`) and an opinionated set of channels for _how_ to deliver, especially for digital and agent-to-agent commerce.

## The five built-in channels

| Channel | Use | Delivery mechanism |
| --- | --- | --- |
| **Inline** | Direct HTTP response | The seller's server returns the asset in the same response that confirms commit (atomic) |
| **Email** | Digital codes, links, instructions | Server sends an email containing the asset or a one-time link |
| **XMTP** | Agent-to-agent, on-chain identity | Server posts to the buyer's XMTP address |
| **Webhook** | Server-to-server | Server POSTs to a URL the buyer provided at commit time |
| **IPFS pointer** | Large files | Server returns an IPFS CID; buyer fetches separately |

The channels are implemented in [`@bosonprotocol/x402-fulfillment`](/reference/x402/x402-fulfillment), but the concept applies to any seller — even an SDK-based marketplace.

## Picking a channel

| Scenario | Channel |
| --- | --- |
| Selling an API call response | Inline |
| Selling a digital license / activation code | Email |
| Selling agent-readable JSON | XMTP or Inline |
| Selling a large file (model weights, dataset) | IPFS pointer |
| Selling a physical good with tracking | Webhook (your fulfillment system posts back) |

## Channel declaration (x402)

In x402, the seller's `402 Payment Required` response advertises which channel(s) it supports. The client picks; the server delivers via that channel after on-chain settlement.

```json
{
  "accepts": [{
    "scheme": "escrow",
    "fulfillment": {
      "channels": [
        { "id": "inline" },
        { "id": "email" }
      ]
    },
    "…": "…"
  }]
}
```

Custom channels can be registered via the `FulfillmentChannel` interface in `x402-fulfillment`.

## Non-x402 delivery

If you're not using x402 — e.g. a marketplace selling physical goods — fulfillment is between your backend and your shipping system. The protocol's contract with you is "the exchange is `REDEEMED`; the buyer has signaled they want the goods." See [Build → Sellers → Handle redemption / deliver](/build/sellers/handle-redemption).

## Reorg / re-delivery safety

Two principles:

1. **Tie delivery to the `VoucherRedeemed` event, not to a subgraph read.** Subgraph lag means you might miss redemptions; the event is the source of truth.
2. **Make delivery idempotent.** Key on `exchangeId`. Re-firing the event (due to a reorg or replay) must not double-deliver. Persist a "delivered" flag per `exchangeId`.

## Common footguns

- **Email delivery is asynchronous.** A buyer who commits and immediately checks email may not see the message for 30+ seconds. Show "delivery in progress" in your UI.
- **Webhook handlers are public endpoints.** Authenticate the request — the simplest is HMAC-sign the payload with a per-exchange secret.
- **XMTP requires the buyer's address to have an XMTP identity.** Not every wallet has one. Have a fallback channel.

## Where to look in code

- [Reference → x402b packages → x402-fulfillment](/reference/x402/x402-fulfillment)
- [Build → Sellers → Handle redemption / deliver](/build/sellers/handle-redemption)
- [Recipes → x402 server email-fulfillment](/recipes/x402-email)

## Next

- [Build with x402 → Fulfillment channels](/x402/fulfillment).
- [Recipes → Webhook server for state changes](/recipes/webhook-server).

---

# Funds, escrow & payouts

URL: https://www.bosonprotocol.io/docs/concepts/funds

> How money flows through Boson — deposits, escrow, fees, payouts, and withdrawal.

# Funds, escrow & payouts

Money in Boson moves through a single on-chain treasury per entity (seller, buyer, agent, DR, royalty recipient). All deposits and withdrawals go through the [`FundsHandlerFacet`](/reference/contracts/facets).

## The lifecycle

::::steps

### Seller deposits to their treasury

Optional — sellers can also rely on per-commit deposit funding.

### Buyer commits to an offer

The buyer's `price` and the seller's `sellerDeposit` lock in escrow.

### Buyer redeems

No fund movement yet. Redemption only starts the dispute window.

### Exchange completes

After the dispute window ends, the buyer's `price` flows to the seller treasury, and the seller's `sellerDeposit` is released back to the seller treasury.

### Seller withdraws

`withdrawFunds` moves the tokens out of the protocol to the seller's treasury address.

::::

Disputes branch step 4 to the [dispute state machine](/concepts/dispute-state-machine), which splits escrow per `buyerPercent`.

## Fees taken at completion

| Fee | Recipient | Taken from |
| --- | --- | --- |
| Protocol fee | Boson protocol treasury | Seller's price share |
| Agent fee | Agent treasury | Seller's price share |
| Dispute resolver fee | DR treasury | Escrow (only on `DECIDED` outcome) |
| Royalty | Royalty recipients | Secondary sales |

Configured per chain and per token via `ConfigHandlerFacet`. Read current values from `coreSdk.getFees()` or the [Fee schedule reference page](/networks/tokens).

## Native vs. ERC-20

- **Native** (ETH, MATIC, etc.) — `exchangeToken` is `address(0)`. Transactions are `payable`; the buyer attaches `msg.value`.
- **ERC-20** (USDC, DAI, etc.) — `exchangeToken` is the token address. The buyer must `approve` the Diamond first (or use a [permit](/concepts/signing) / [ERC-3009](/concepts/signing)) — see [Approve · Permit · Permit2 troubleshooting](/troubleshooting/approvals).

## Withdrawal

Funds in a treasury are inert until withdrawn. Use:

- `withdrawFunds(entityId, tokenList, amountsList)` — SDK
- `withdraw_funds` — MCP

The treasury _address_ is set at seller / agent creation and can be updated.

## Common footguns

- **Withdrawals are not instant earnings.** Funds enter the treasury only when an exchange `COMPLETED`s (or is otherwise terminated favorably). Until then they're in escrow.
- **Per-offer seller deposit vs. seller-treasury deposit.** Most offers have `sellerDeposit = 0`; the seller stakes only when they want skin in the game for high-trust offers.
- **Token addresses are chain-specific.** USDC on Polygon ≠ USDC on Base ≠ USDC on Mainnet. Pull the right address from [Supported tokens](/networks/tokens).

## Where to look in code

- [Reference → Core SDK → Funds mixin](/reference/core-sdk/funds)
- [Reference → MCP tools](/reference/mcp-tools) → `deposit_funds`, `withdraw_funds`, `get_funds`
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `FundsHandlerFacet`

## Next

- [Build → Sellers → Manage funds](/build/sellers/manage-funds).
- [Networks → Supported tokens](/networks/tokens).

---

# The metadata pipeline

URL: https://www.bosonprotocol.io/docs/concepts/metadata

> How offer metadata is built, validated, pinned to IPFS, and referenced on-chain.

# The metadata pipeline

Boson offers carry their off-chain detail (title, description, images, attributes, contractual agreement) as a **metadata document** pinned to IPFS. The Diamond stores only the IPFS URI and a content hash.

::::steps

### Build

Construct the metadata JSON object against the appropriate schema.

### Validate

Run `validate_metadata` (or `validateMetadata` in the SDK) — Yup schema check, no return value; raises on invalid.

### Pin

Upload to IPFS via `storeMetadata` (or any pinning service). The CID becomes your metadata URI.

### Reference

Pass the `ipfs://Cid…` URI to `createOffer`. The SDK computes and stores the content hash on-chain alongside the URI.

::::

## Schemas

Three top-level schemas, defined by `@bosonprotocol/metadata`. The package exports the Yup schemas (`productV1MetadataSchema`, `bundleMetadataSchema`, etc.) and `validateMetadata`. Applications construct the metadata object literal that matches the schema — there are no high-level `*Factory()` helpers.

| Schema | When |
| --- | --- |
| `PRODUCT_V1` | Physical or simple digital products |
| `BUNDLE` | Multi-item bundles (e.g. license + shirt) |
| `BASE` | Minimum schema for opaque offers |

There's also `SELLER`, `COLLECTION`, and `rNFT` metadata for the entities surrounding an offer.

## Build → validate → pin

```ts twoslash
// @noErrors
// Construct the PRODUCT_V1 object directly — see Reference → Metadata schemas
// for the full required-field list (schemaUrl, type, uuid, name, description,
// externalUrl, licenseUrl, image, attributes, product, seller, shipping,
// exchangePolicy).
import { IpfsMetadataStorage } from "@bosonprotocol/ipfs-storage"
import { validateMetadata } from "@bosonprotocol/metadata"

const uuid = crypto.randomUUID()
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "PRODUCT_V1" as const,
  uuid,
  name: "Hand-thrown mug",
  description: "Stoneware, 12 oz.",
  externalUrl: `https://example.com/${uuid}`,
  licenseUrl: `https://example.com/${uuid}/license`,
  image: "https://cdn.example.com/mug.jpg",
  attributes: [
    { traitType: "Material", value: "Stoneware" },
    { traitType: "Size", value: "12 oz" },
  ],
  // product, seller, shipping, exchangePolicy …
}

const storage = new IpfsMetadataStorage(validateMetadata, { url: process.env.IPFS_URL! })
const metadataUri = await storage.storeMetadata(metadata)
// → "ipfs://Qm…"
```

`metadataUri` is what you pass to `createOffer`. The SDK will compute and store the content hash on-chain alongside the URI.

## Validation

`validate_metadata` (MCP) / `validateMetadata` (SDK) runs the schema check. Errors are structured per JSON-pointer:

```json
{
  "valid": false,
  "errors": [
    { "path": "/productV1/title", "message": "required" }
  ]
}
```

Validate _before_ pinning; otherwise you'll waste an IPFS write.

## Pinning

`@bosonprotocol/ipfs-storage` is a thin wrapper over an IPFS HTTP API. Use [Infura](https://infura.io), [Pinata](https://www.pinata.cloud), or self-host. Always pin _at least three places_ if you care about durability — IPFS does not guarantee availability.

## Contractual agreement

A `PRODUCT_V1` metadata can carry a `contractualAgreement` markdown blob. The MCP `render_contractual_agreement` tool resolves it server-side. See [Reference → MCP tools](/reference/mcp-tools).

## Limits

- Total metadata size: **20 MB**. Most offers come in under 100 KB. Large images should live on a CDN, not in IPFS metadata.
- Image references: HTTPS or `ipfs://`. Avoid `http://` (some viewers refuse).

## Common footguns

- **`validate_metadata` errors are not always actionable.** A schema mismatch deep in a nested field can surface as a generic "required" at a higher path. Always check `errors[*].path` precisely.
- **IPFS gateway lag.** The pin is live on the gateway you posted to, but propagation to other gateways takes minutes. If your frontend fetches via a different gateway than your seller posted to, you may get a 404 for the first few minutes.
- **Don't bake mutable URLs into metadata.** If `images[0].url` points to a Twitter image, it can rot. Use CDN URLs or `ipfs://` references.

## Where to look in code

- [Reference → Metadata schemas](/reference/metadata)
- [Reference → MCP tools](/reference/mcp-tools) → `validate_metadata`, `store_product_v1_metadata`, `store_bundle_metadata`, `store_base_metadata`, `render_contractual_agreement`
- [Reference → Core SDK → Offers](/reference/core-sdk/offers)

## Next

- [Build → Sellers → Publish an offer](/build/sellers/publish-offer).
- [Troubleshooting → Metadata validation](/troubleshooting/metadata).

---

# The Boson model

URL: https://www.bosonprotocol.io/docs/concepts/model

> The three core entities — Offer, Exchange, Dispute — and how they relate.

# The Boson model

The whole protocol revolves around three on-chain entities. If you understand these and the [state machines](/concepts/exchange-state-machine), everything else falls into place.

## Offer

An **offer** is a seller's listing: a thing for sale at a price, valid for a window, with an associated [dispute resolver](/concepts/roles#dispute-resolver), optional token-gating condition, and a pointer to off-chain [metadata](/concepts/metadata).

Created by `createOffer()`. Voided by `voidOffer()`. Lives forever on-chain; cannot be "deleted".

Key fields:

- `price` — what the buyer pays.
- `sellerDeposit` — what the seller stakes (slashed on a lost dispute).
- `buyerCancelPenalty` — what the buyer forfeits if they cancel after commit.
- `exchangeToken` — `0x0` for native (ETH / MATIC), otherwise an ERC-20.
- `quantityAvailable` — how many units can be committed before the offer sells out.
- `valid{From,Until}DateInMS` — commit window.
- `voucherRedeemable{From,Until,ValidDuration}` — redeem window (relative to commit).
- `disputeResolverId` — who arbitrates if things go wrong.
- `metadataUri` / `metadataHash` — IPFS pointer to the off-chain product detail.

See [Build → Sellers → Publish an offer](/build/sellers/publish-offer) for the task; [Reference → Core SDK → Offers](/reference/core-sdk/offers) for full types.

## Exchange

An **exchange** is a specific buyer's commitment to a specific offer. One offer → many exchanges (one per buyer commit). Each exchange has:

- A numeric `exchangeId`.
- A `state` (see [Exchange state machine](/concepts/exchange-state-machine)).
- A single buyer, a single seller, a single offer.
- A linked voucher (rNFT) held in the buyer's wallet until redemption.

The exchange is **the unit of state** in Boson. Every protocol action — commit, redeem, complete, cancel, dispute — moves an exchange between states.

See [Build → Buyers → Commit to an offer](/build/buyers/commit) for the buyer side.

## Dispute

A **dispute** is an exchange that's run into trouble after redemption. Modeled as a separate on-chain entity attached to its parent exchange.

- Raised by the buyer with `raiseDispute()` within the **dispute window**.
- Resolved mutually (`resolveDispute()`) within the **resolution window**.
- Otherwise escalated to the dispute resolver (`escalateDispute()`) for a binding `decideDispute()` or `refuseEscalatedDispute()`.

Disputes have their own [state machine](/concepts/dispute-state-machine), distinct from the exchange's.

See [Build → Buyers → Raise a dispute](/build/buyers/raise-dispute) and [Build → Dispute Resolvers](/build/dispute-resolvers).

## The relationship

```mermaid
flowchart LR
    Seller([Seller])
    Buyer([Buyer])
    DR([Dispute resolver])

    Seller -->|creates| Offer[Offer]
    Offer -->|1 → many| Exchange[Exchange]
    Buyer -.->|commits to| Exchange
    Exchange -->|mints| Voucher[Voucher rNFT]
    Exchange -.->|optional| Dispute[Dispute]
    DR -.->|decides| Dispute
```

Once you grok these three, the rest of the protocol is variations:
- [**Bundles**](/build/sellers/bundles-variants) — an offer that ships multiple items.
- [**Token-gated offers**](/build/marketplace/token-gated) — an offer with a condition restricting who may commit.
- [**Pre-minted vouchers**](/build/sellers/pre-minted-vouchers) — vouchers minted before any commit.
- [**Atomic commit-and-redeem**](/build/buyers/atomic-commit-redeem) — collapse two state transitions into one tx.
- [**Buyer-initiated offers**](/build/buyers/buyer-initiated) — the buyer drafts, the seller accepts.
- [**Sequential commit**](/build/buyers/sequential-commit) — secondary-market resale through the protocol with chained buyer protection and perpetual royalties.

## Next

- [Roles](/concepts/roles) — who can do what.
- [Exchange state machine](/concepts/exchange-state-machine) — every state transition.
- [Networks & ConfigIds](/concepts/networks-and-configids) — selecting a deployment.

---

# Networks & ConfigIds

URL: https://www.bosonprotocol.io/docs/concepts/networks-and-configids

> How Boson identifies a deployment — environment, chain, and version index.

# Networks & ConfigIds

Boson is deployed on multiple chains, in multiple environments, and the Diamond can be redeployed to a new index when there's a breaking upgrade. Every SDK call, MCP tool call, and widget embed takes a single string that disambiguates all three:

```
${envName}-${chainId}-${index}
```

Examples:

- `staging-84532-0` — Base Sepolia testnet, staging environment, index 0.
- `staging-80002-0` — Polygon Amoy testnet.
- `staging-11155111-0` — Sepolia.
- `production-137-0` — Polygon mainnet.
- `production-1-0` — Ethereum mainnet.
- `production-8453-0` — Base mainnet.
- `production-10-0` — Optimism mainnet.
- `production-42161-0` — Arbitrum mainnet.

For the full machine-readable list see [Networks → ConfigIds matrix](/networks/configids). For deployed contract addresses see [Networks → Contract addresses](/networks/addresses).

## Why the index?

When the Diamond is upgraded in a breaking way (rare; protocol-level change), a new deployment is published with a new index. Old `index-0` continues to function for legacy exchanges; new offers point to `index-1`. The `configId` makes the choice explicit.

If a chain has never been upgraded, its index is always `0` and you can ignore the discriminator.

## Discovering ConfigIds at runtime

```ts twoslash
// @noErrors
import { getEnvConfigs } from "@bosonprotocol/common"
const ids = (["local", "testing", "staging", "production"] as const)
  .flatMap((env) => getEnvConfigs(env).map((c) => c.configId))
// or via MCP:
//   get_config_ids → { ids: ["staging-84532-0", ...] }
```

## Switching environments

The recommended pattern is one ConfigId per deployment environment:

```ts twoslash
// @noErrors
const CONFIG_ID = process.env.NODE_ENV === "production"
  ? "production-137-0"
  : "staging-84532-0"
```

Cross-checking: the same seller/buyer/offer IDs **do not** exist across environments. An offer with `id = 42` on staging is unrelated to `id = 42` on production.

## Picking a network

A few rules of thumb:

| Use case | Recommended |
| --- | --- |
| Testing | `staging-84532-0` (Base Sepolia) — cheap, fast |
| Polygon-heavy ecosystems | `production-137-0` |
| L2-first apps | `production-8453-0` (Base) or `production-42161-0` (Arbitrum) |
| Maximum decentralization perception | `production-1-0` (Ethereum mainnet) — most expensive |

See the per-chain [Contract addresses](/networks/addresses) and [Subgraph endpoints](/networks/subgraph) for the deployment specifics.

## Common footguns

- **Don't hard-code the chain ID.** Use the `configId`; it carries the env and version too.
- **Don't use a production ConfigId in a staging app.** The staging dApp and widget host won't load production offers.
- **Use `coreSdk.getConfig()` to read the config that's actually loaded.** This is the safest source of truth for subgraph URL, contract addresses, and supported tokens.

## Next

- [Networks → ConfigIds matrix](/networks/configids) — machine-readable table.
- [Networks → Supported tokens](/networks/tokens) — which ERC-20s work where.
- [Going to production](/concepts/production) — checklist before swapping envs.

---

# Offer lifecycle

URL: https://www.bosonprotocol.io/docs/concepts/offer-lifecycle

> The states an offer passes through from creation to terminal.

# Offer lifecycle

Offers are simpler than [exchanges](/concepts/exchange-state-machine). They have effectively four reachable states:

```mermaid
stateDiagram-v2
    [*] --> ACTIVE: createOffer
    ACTIVE --> VOIDED: voidOffer (seller)
    ACTIVE --> EXPIRED: validUntilDate passes
    ACTIVE --> SOLD_OUT: quantityAvailable == 0
    VOIDED --> [*]
    EXPIRED --> [*]
    SOLD_OUT --> [*]
```

## What each state means

- `ACTIVE` — buyers can still commit. The default.
- `VOIDED` — seller has retracted the offer. No new commits accepted. Existing exchanges continue independently.
- `EXPIRED` — `validUntilDate` has passed.
- `SOLD_OUT` — `quantityAvailable` has decremented to zero through commits.

These states are **derived**, not stored. The subgraph and SDK compute them from `voided` (bool on-chain), `validUntilDate`, and `quantityAvailable`.

## Voiding non-listed offers

For non-listed (private / EIP-712) offers — those that exist as a signed [`FullOffer`](/concepts/signing#fulloffer-eip-712) but haven't been written on-chain — voiding goes through `void_non_listed_offer` (or `_batch`) on the MCP, or the equivalent SDK method. The on-chain side records the offer hash as voided so it can't subsequently be committed to.

## Common footguns

- **Voiding does not refund seller deposit.** Deposits are per-exchange, not per-offer; nothing is locked at creation. Any deposited, but not yet encumbered funds can be freely witdrawn.
- **An offer can `EXPIRE` while exchanges from it are still live.** The two state machines are independent.
- **`SOLD_OUT` is observed, not declared.** If you need precise inventory, read `quantityAvailable` from the contract, not the subgraph, to avoid lag.

## Next

- [Build → Sellers → Publish an offer](/build/sellers/publish-offer).
- [Build → Marketplace operators → Search & discovery](/build/marketplace/search) for filtering by state.

---

# Going to production

URL: https://www.bosonprotocol.io/docs/concepts/production

> Operational checklist before flipping from staging to production.

# Going to production

You've built a thing on staging. Before you flip `configId` from `staging-*` to `production-*`, walk this list.

## Security

- [ ] **Private keys in a managed signer** (KMS, Vault, Fireblocks, Privy, Turnkey). _Never_ in env vars on a long-running host.
- [ ] **Smart account for sellers**, ideally with a session key for the assistant role.
- [ ] **Restricted RPC API keys** — at least to your server's IP range.
- [ ] **Per-environment ConfigId** — `process.env`-gated, not hardcoded.
- [ ] **HMAC-signed webhook payloads** for your fulfillment endpoints.
- [ ] **CSP allowlist** for widget embeds (`script-src https://widgets.bosonprotocol.io`).

## On-chain hygiene

- [ ] **Verify contract addresses** against the official [Contract addresses table](/networks/addresses) before any integration.
- [ ] **Read `protocol.pausedRegions()`** before a call. Treat a paused region as a transient failure.
- [ ] **Subscribe to facet upgrade events.** Subscribe to the Diamond's `DiamondCut` event so you know when the protocol is upgraded under you.
- [ ] **Pin SDK and contract ABI versions** to the same release tag.
- [ ] **Monitor your wallet's gas balance.** Drain alerts at 0.5×, 0.2×, 0.1× the expected daily burn.

## Operational

- [ ] **Idempotent writes.** Every state-changing call keyed on `(exchangeId, target state)` or a request ID.
- [ ] **Subgraph lag handled.** `waitForGraphNodeIndexing` on every read-after-write path. See [Eventing & indexing](/concepts/eventing).
- [ ] **Reorg handling.** 2–3 confirmations on L2s, 12+ on Mainnet, before treating a state change as final.
- [ ] **Rate-limit Biconomy / facilitator calls.** Have a fallback for when the relayer is down.
- [ ] **Persist webhook events with `(txHash, logIndex)` as the dedupe key.**
- [ ] **Health-check the subgraph.** Alert if its head-block falls more than ~20 behind chain head.

## Money

- [ ] **Withdrawals are not automatic.** Schedule a job to call `withdraw_funds` periodically or on a balance threshold.
- [ ] **Test the full state machine on a real exchange before flipping to production.** Including a dispute path.
- [ ] **Document who has admin keys for the seller and how to rotate them.** This is a real fire drill.
- [ ] **Calculate effective fee, gas, and FX exposure per exchange.** Use [Networks → Supported tokens](/networks/tokens) for fee tables.

## Observability

- [ ] **Log every tool call with an `exchangeId`.** Indexable, searchable, replayable.
- [ ] **Dashboards**: open exchanges, redemption rate, dispute rate, time-to-completion, gas spent.
- [ ] **Alerts**: dispute raised, exchange disputed > 1 day, wallet balance low, subgraph stale.
- [ ] **Tracing** across SDK → RPC → relayer → chain → subgraph for one canonical request.

## Code

- [ ] **No `console.log` of private keys, signatures, or full transaction objects.** Easier to leak than you think.
- [ ] **Catch and surface tx revert reasons.** Use `sdk.parseError()` or decode against the merged ABI.
- [ ] **Type-check SDK + MCP call sites** (Twoslash in docs is your friend during integration).
- [ ] **End-to-end smoke test** that runs against production every release, using a known test offer.

## When something breaks

- [Troubleshooting → Reverts & error codes](/troubleshooting/reverts).
- [Troubleshooting → Subgraph indexing lag](/troubleshooting/indexing-lag).
- [Troubleshooting → Signature mismatches](/troubleshooting/signatures).
- [Troubleshooting → FAQ](/troubleshooting/faq).

---

# Roles

URL: https://www.bosonprotocol.io/docs/concepts/roles

> Seller, Buyer, Dispute Resolver, Protocol Agent, Royalty Recipient, Facilitator — what each can do and how they're created.

# Roles

Boson has six distinct roles. A single wallet can hold any combination of them.

| Role | Created by | Primary action |
| --- | --- | --- |
| [Seller](#seller) | `createSeller()` | Publishes offers |
| [Buyer](#buyer) | `createBuyer()` (implicit on first commit) | Commits to offers |
| [Dispute Resolver](#dispute-resolver) | `createDisputeResolver()` | Arbitrates contested exchanges |
| [Protocol Agent](#protocol-agent) | `createAgent()` | Earns a fee for facilitating an offer |
| [Royalty Recipient](#royalty-recipient) | `addRoyaltyRecipients()` | Receives a cut of secondary sales |
| [Facilitator (x402)](#facilitator) | (off-chain only) | Relays signed meta-txs to the Diamond |

## Seller

The entity that publishes offers. Has four keys at creation:

- `assistant` — the operational signer. Calls `createOffer()`, `voidOffer()`, etc.
- `admin` — the privileged signer. Updates the seller's configuration.
- `clerk` — _deprecated_
- `treasury` — the recipient address for offer proceeds.

Sellers can hold an optional `authToken` (e.g. a Lens Protocol token) to associate the on-chain identity with an off-chain handle.

See [Build → Sellers](/build/sellers).

## Buyer

The entity that commits. Created implicitly the first time an address calls `commitToOffer()` or `createOffer()` (for buyer-initiated offers). No separate setup required.

See [Build → Buyers](/build/buyers).

## Dispute Resolver

A third party registered to arbitrate disputed exchanges. Configured with:

- A fee per chain × token.
- An optional metadata URI describing terms of service.
- A list of allowed sellers (or "anyone").

Examples: a centralised arbitration service, a multisig, [Kleros](https://kleros.io), or a custom DAO. See [Build → Dispute Resolvers](/build/dispute-resolvers).

## Protocol Agent

> Distinct from an **AI agent**. The protocol uses the word "agent" to mean a third party that earns a fee for facilitating an offer.

Configured on the offer at creation (`agentId`). On exchange completion, the agent's treasury receives a fixed percentage of the offer price. Used by marketplaces, integrators, and curators who add value but don't sell directly.

Register with `register_agent` ([MCP](/reference/mcp-tools)) or `createAgent` ([SDK](/reference/core-sdk/accounts)).

## Royalty Recipient

Registered per seller; gets a percentage of secondary-sale royalties on rNFTs. See [Build → Sellers → Royalties](/build/sellers/royalties).

## Facilitator

An off-chain role specific to the [x402 stack](/x402). A facilitator relays a buyer's signed meta-transaction + token authorization to the Diamond, paying gas on the buyer's behalf. Operationally similar to a Biconomy relayer, but specialized to the x402 envelope.

See [Build with x402 → Facilitator](/x402/facilitator).

---

# Signing & meta-transactions

URL: https://www.bosonprotocol.io/docs/concepts/signing

> The canonical reference for every signing flow in Boson — direct, meta-tx, ERC-3009, EIP-2612, Permit2, and FullOffer EIP-712.

# Signing & meta-transactions

Every state-changing call to Boson is signed. There are five distinct signing flows; this page is the canonical reference for all of them. Anywhere else in the docs that mentions signing links _here_, not to a duplicate explainer.

## At a glance

| Flow | Who signs | Who pays gas | Where it's used |
| --- | --- | --- | --- |
| [Direct on-chain](#direct-on-chain) | The user/caller | The user/caller | Default for SDK and `send_signed_transaction` |
| [Boson meta-tx (Biconomy)](#boson-meta-tx-biconomy) | The user | A relayer | Gas-less UX for users |
| [Token-auth meta-tx](#token-auth-meta-tx) | The user (+ token sig) | A relayer | Gas-less UX for users |
| [FullOffer EIP-712](#fulloffer-eip-712) | The offer creator | (varies) | Non-listed (private) offers, x402 |
| [Mutual dispute resolution](#mutual-dispute-resolution) | Buyer + seller (both) | Whoever submits | `resolveDispute` |

## Direct on-chain

You sign and broadcast yourself. The SDK does this transparently when you call `sdk.commitToOffer(...)` etc.

For MCP-driven agents, the **3-step pattern**:

1. Call the tool (e.g. `commit_to_offer`) → returns an unsigned `{ to, data, value, gasLimit, chainId }`.
2. Sign locally with your wallet.
3. Broadcast via `send_signed_transaction` or your own RPC.

```ts twoslash
// @noErrors
const unsigned = await mcp.commitToOffer({ /* … */ })
const signed = await wallet.signTransaction(unsigned)
await mcp.sendSignedTransaction({ chainId: 84532, signedTx: signed })
```

See [Build for AI agents → The 3-step signing pattern](/agents/signing) for the agent-specific deep dive.

## Boson meta-tx (Biconomy)

The user signs an EIP-712 envelope; a relayer (Biconomy or your own) calls `MetaTransactionsHandlerFacet.executeMetaTransaction` and pays gas.

```ts twoslash
// @noErrors
// Sign on the client:
const signedMetaTx = await sdk.metaTx.signMetaTxCommitToOffer({
  buyer: userAddress,
  offerId,
})

// Relay (either via Biconomy directly, or your own forwarder):
await sdk.metaTx.relayMetaTransaction(signedMetaTx)
```

Or via MCP:

```
send_meta_transaction { chainId, functionName, functionSignature, userAddress, nonce, signature }
```

## Token-auth meta-tx

Th user can pay the protocol in a single signed envelope, without prior `approve`. Three variants:

- **ERC-3009** — `receiveWithAuthorization` (used by USDC, EURC, others).
- **EIP-2612 Permit** — for tokens that implement `permit`.
- **Permit2** — the [Uniswap Permit2](https://docs.uniswap.org/contracts/permit2/overview) variant.

The relayed call is `executeMetaTransactionWithTokenTransferAuthorization`. See [Reference → Contracts → Diamond facets → MetaTransactionsHandlerFacet](/reference/contracts/facets).

Via MCP:

```
send_forwarded_meta_transaction {
  chainId, functionName, functionSignature, userAddress, nonce, signature,
  tokenAuth: { type: "ERC3009" | "Permit" | "Permit2", … }
}
```

## FullOffer EIP-712

A `FullOffer` is a seller-signed payload representing an offer that hasn't been written on-chain. Used for non-listed (private) offers and for the [x402 stack](/x402).

```ts twoslash
// @noErrors
const fullOffer = await sdk.signFullOffer({ /* offer params */ })
// fullOffer.signature, fullOffer.offerHash, …

// Later, atomic commit:
await sdk.createOfferAndCommit({ fullOffer })
```

The signature can be verified on-chain (EOA or EIP-1271 smart account). The hash, once committed, is recorded as used so it can't be re-played.

## Mutual dispute resolution

`resolveDispute` requires _both_ buyer and seller to sign the same payload (offering `buyerPercent`). Whichever party submits the on-chain call attaches both signatures.

See [Build → Buyers → Raise a dispute](/build/buyers/raise-dispute) and [Recipes → Mutual dispute resolution](/recipes/mutual-dispute).

## Nonce management

Each user has a per-chain nonce in the Diamond's `MetaTransactionsHandlerFacet`. Read with `isUsedNonce(address, nonce)`. The SDK reads + bumps for you; agents using raw MCP must manage their own.

## Common footguns

- **Mismatched EIP-712 typed-data.** The SDK builds the payload _identically_ to the on-chain verifier. Don't hand-build typed-data; always use `sdk.metaTx.signMetaTx*` or the MCP `sign_*` tools.
- **Stale nonces under concurrency.** If two transactions for the same user are signed in parallel with the same nonce, one will fail. Serialize or use distinct nonces.
- **Permit2 has a different domain separator than EIP-2612.** Don't mix them.
- **`signTypedData` UI varies wildly across wallets.** Test with MetaMask, Coinbase Wallet, and a hardware wallet before assuming any signed-data flow works.

## Where to look in code

- [Reference → Core SDK → MetaTx mixin](/reference/core-sdk/meta-tx)
- [Reference → MCP tools](/reference/mcp-tools) → `sign_full_offer`, `send_meta_transaction`, `send_native_meta_transaction`, `send_forwarded_meta_transaction`, `send_signed_transaction`
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `MetaTransactionsHandlerFacet`

## Next

- [Troubleshooting → Signature mismatches](/troubleshooting/signatures).
- [Troubleshooting → Approve · Permit · Permit2](/troubleshooting/approvals).
- [Recipes → Gas-less commit (Biconomy)](/recipes/gasless-commit).

---

# Wallets & key management

URL: https://www.bosonprotocol.io/docs/concepts/wallets

> How Boson talks to wallets — browser, server EOA, MPC, smart accounts, session keys, and the agent-wallet patterns.

# Wallets & key management

Boson is signer-agnostic. The SDK takes a `Web3LibAdapter`; the MCP server never sees keys (it returns unsigned transactions). The question is _how_ your code holds and uses keys.

## The five patterns

| Pattern | When | Notes |
| --- | --- | --- |
| **Browser wallet** (MetaMask, Coinbase Wallet, WalletConnect, RainbowKit) | Human-facing apps | Standard; integrate via `EthersAdapter(provider, provider.getSigner())`. |
| **Server EOA** | Backend automation, dev/staging | Easy. Risky in production — protect with KMS, vault, restricted IP. |
| **MPC / threshold sig** (Fireblocks, Privy, Turnkey, etc.) | Multi-party custody | Bridge to ethers/viem; your provider's SDK gives you a signer. |
| **Smart account** (Safe, ERC-4337) | Programmable rules, batched ops, session keys | Sign through the account's userOp flow; relay via your bundler. |
| **Session key** | Agent commerce, mobile apps | Short-lived key scoped to specific actions, delegated from a master account. |

Pick the pattern that matches your security model. Boson doesn't care which.

## Browser wallet (typical Next.js / React app)

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { ethers } from "ethers"

const provider = new ethers.providers.Web3Provider(window.ethereum)
const signer = provider.getSigner()

const sdk = CoreSDK.fromDefaultConfig({
  web3Lib: new EthersAdapter(provider, signer),
  envName: "production",
  configId: "production-137-0",
})
```

## Server EOA (Node script, cron, queue worker)

```ts twoslash
// @noErrors
import { ethers } from "ethers"
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL)
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)
// pass `wallet` to EthersAdapter the same way
```

In production, **never** hold private keys in environment variables on a long-running host. Use AWS KMS, Hashicorp Vault, or a managed signer (Fireblocks, Privy, Turnkey). The SDK doesn't care; just hand it an object with `signMessage`, `signTransaction`, etc.

## Agent wallets

Autonomous agents call state-changing tools in tight loops. Special considerations:

- **Nonce management.** Don't send tx N+1 before tx N is mined unless you're tracking nonces yourself.
- **Gas funding.** Refill the agent wallet automatically if it dips below a threshold.
- **Spending caps.** Use a smart account with a session key bounded by max-spend rules.
- **Restart safety.** On crash, check on-chain state (e.g. `get_exchanges`) before re-trying — see [Idempotency & retry](/agents/idempotency).

For deep coverage: [Build for AI agents → Wallet patterns](/agents/wallets).

## Smart accounts

A Safe (multisig) can be a seller or buyer. The SDK signs typed data with the smart account; the Safe owners co-sign offline; the resulting Safe-tx is what hits the Diamond.

For ERC-4337 accounts, the SDK builds the inner calldata; you wrap it in a userOp and send to a bundler. The Diamond's meta-tx facet accepts EIP-1271 signatures (smart-account signatures), so this works out of the box.

## Session keys

Use these to delegate scoped authority to an agent or mobile app:

1. Master account (Safe / 4337) authorizes a session key.
2. Session key signs Boson actions within a scope (max value, allowed selectors, time-boxed).
3. Master can revoke any time.

Useful for sandboxing an autonomous buyer agent so it can spend ≤ $100/day on commits, redeem, and dispute — but nothing else.

## Common footguns

- **MetaMask switches networks asynchronously.** If you switch from L1 to L2 mid-flow, your provider may still be on the old chain for a beat. Always check `provider.network` before broadcasting.
- **Hardware wallets can be slow with EIP-712.** Build in a 30s timeout for `signTypedData`, and don't auto-retry — you'll just trigger a second user-confirm dialog.
- **Don't reuse a buyer wallet as a seller treasury.** It works, but it conflates accounting. Different wallets for different roles.

## Next

- [Signing & meta-transactions](/concepts/signing) — what gets signed, and the meta-tx options.
- [Build for AI agents → Wallet patterns](/agents/wallets) — agent-specific deep dive.
- [Going to production](/concepts/production) — checklist.

---

# Build — Buyers

URL: https://www.bosonprotocol.io/docs/build/buyers

> Everything a buyer can do on Boson, organized by task.

# Build — Buyers

A **buyer** commits to offers, redeems vouchers, and (rarely) disputes. There's no explicit "create a buyer" step — your first `commitToOffer` registers you.

For each task, expand the **CodeGroup** to see the equivalent code in SDK and MCP.

## Tasks

1. [Discover offers](./buyers/discover) — query offers from the subgraph.
2. [Commit to an offer](./buyers/commit) — the core action.
3. [Atomic commit-and-redeem](./buyers/atomic-commit-redeem) — single-tx purchase + redemption.
4. [Buyer-initiated offers](./buyers/buyer-initiated) — propose to a seller.
5. [Sequential commit](./buyers/sequential-commit) — buy a voucher on a secondary market with full protocol protection.
6. [Redeem a voucher](./buyers/redeem) — claim the goods.
7. [Cancel / revoke](./buyers/cancel) — back out of a commit.
8. [Raise a dispute](./buyers/raise-dispute) — when things go wrong.

## Non-code path

9. [Buy via the Boson dApp](./buyers/dapp) — UI walkthrough.

## Prerequisites

- A wallet with the offer's `exchangeToken` (or native gas) on the chain you're buying on. See [Wallets & key management](/concepts/wallets).
- Approval for ERC-20 offers (or use a [permit](/concepts/signing)). See [Troubleshooting → Approve · Permit · Permit2](/troubleshooting/approvals).

---

# Atomic commit-and-redeem

URL: https://www.bosonprotocol.io/docs/build/buyers/atomic-commit-redeem

> Commit and redeem in a single transaction — the right pattern for instant digital delivery.

# Atomic commit-and-redeem

For digital goods that are delivered instantly, splitting commit and redeem into two transactions adds friction and a window where the buyer pays but hasn't redeemed. Atomic commit-and-redeem collapses them into a single on-chain tx via `OrchestrationHandlerFacet`.

:::code-group

```ts twoslash [SDK]
// @noErrors
// The Core SDK doesn't (yet) wrap atomic commit+redeem behind a single helper.
// Two practical options:
//
//   1) Two-step commit then redeem — the buyer's wallet signs twice, but the
//      delivery surface stays simple:
const commitTx = await sdk.commitToOffer(offerId, { value: offer.price })
const commitReceipt = await commitTx.wait()
const exchangeId = sdk.getCommittedExchangeIdFromLogs(commitReceipt.logs)
await (await sdk.redeemVoucher(exchangeId)).wait()
//
//   2) Drive the Diamond's OrchestrationHandlerFacet directly via ethers — that
//      facet exposes the combined entry point on-chain. See
//      Reference → Contracts → Facets → Orchestration.
```

```ts twoslash [MCP]
// @noErrors
const { unsignedTx } = await mcp.commitToOffer({
  configId: "production-137-0",
  signerAddress: wallet.address,
  buyer: wallet.address,
  offerId,
  redeem: true,                // redeem in same tx
})
```
:::

## When to use

- **Digital delivery** with the seller's server returning the asset in the same HTTP response (common with [x402](/x402)).
- **Agents** that don't want to track a `COMMITTED → REDEEMED` two-step state machine.
- **One-shot purchases** with no redemption window logic.

## When not to use

- **Physical goods.** You need the redemption signal to be _the buyer received it in their hands_, not _they committed_. Use two-step commit-then-redeem.
- **Time-bounded redemption windows.** If you want the buyer to redeem within N days, two-step is required.

## Atomic offer + commit + redeem

Sellers can publish an offer and atomically commit a buyer in one tx via the SDK's
`createOfferAndCommit` (orchestration). To also redeem in the same call, drive the
Diamond's `OrchestrationHandlerFacet` directly — at this SDK version there's no
single helper that wraps offer+commit+redeem.

```ts twoslash
// @noErrors
// 1. Seller signs a FullOffer off-chain
const signedFullOffer = await sdk.signFullOffer(fullOfferDraft)

// 2. Buyer (or the seller acting for the buyer) calls createOfferAndCommit
await sdk.createOfferAndCommit(signedFullOffer)
//
//    For the additional redeem step, call OrchestrationHandlerFacet via ethers.
```

See [Concepts → Signing → FullOffer](/concepts/signing#fulloffer-eip-712) and
[Reference → Core SDK → Orchestration mixin](/reference/core-sdk/orchestration).

## Next

- [Quickstart → x402 server](/quickstart/x402-server) — atomic flow over HTTP.
- [Build with x402 → State-machine integration](/x402/state-machine).
- [Reference → Core SDK → Orchestration mixin](/reference/core-sdk/orchestration).

---

# Buyer-initiated offers

URL: https://www.bosonprotocol.io/docs/build/buyers/buyer-initiated

> The buyer drafts an offer; the seller accepts. RFQ, procurement, agent-driven demand — inverted Boson commerce.

# Buyer-initiated offers

In normal Boson, the seller writes an offer first; the buyer commits. Buyer-initiated offers invert that — a buyer drafts an offer (price, terms, validity window) and **deposits** the price into their protocol treasury. A seller who likes the terms calls `commitToBuyerOffer`, encumbering their `sellerDeposit`. From there the protocol flow is identical to a seller-created offer: voucher is minted, redemption clock starts, dispute window opens, etc.

Use cases:

- **Request for quote (RFQ)** — buyer specifies what they want; sellers respond.
- **Bespoke services** — the spec _is_ the offer.
- **Procurement** — purchase orders with on-chain enforcement.
- **Agent-driven demand** — autonomous buyer agents publish offers; seller agents discover and fulfil. Expected to be the most common usage in the agentic-commerce era.

## What changes vs a seller-initiated offer

| Aspect | Seller-initiated | Buyer-initiated |
| --- | --- | --- |
| Who calls `createOffer` | Seller assistant | Buyer |
| `creator` field on offer | `SELLER` | `BUYER` |
| `sellerId` set at create time? | Yes | **No** — fixed when seller commits |
| `collectionIndex`, royalty info, mutualizer set at create? | Yes | **No** — set when seller commits via `commitToBuyerOffer` |
| Conditional / token-gated commits | Allowed | **Disallowed** — buyers don't get to gate sellers |
| Price-discovery offers | Allowed | **Disallowed** — only static prices |
| Funds encumbered up front | Seller deposit | **Buyer's price** — funds the buyer pre-deposited |
| Funds encumbered at commit | Buyer's price | Seller's deposit |
| Voucher recipient | Buyer | Buyer (unchanged) |
| Emitted event on commit | `BuyerCommitted` | **`SellerCommitted`** |

After commit, redemption / dispute / completion flows are identical to a normal exchange.

## Buyer side: draft the offer

The buyer:

1. **Deposits funds** to their buyer treasury (the price they'll pay if a seller commits).
2. **Creates the offer**, with `creator = BUYER`, `sellerId = 0`, and no royalty / collection / mutualizer.
3. **Publishes off-chain** (XMTP, RFQ board, partner site, agent network) so sellers can find it.
4. **Withdraws** any unmatched funds after the validity window if no seller commits.

:::code-group

```ts twoslash [SDK]
// @noErrors
// 1. Deposit price into buyer treasury
await (await sdk.depositFunds(buyerId, /* amount */ price, exchangeToken)).wait()

// 2. Create the buyer-initiated offer
//    The SDK detects creator=BUYER and uses commitToBuyerOffer machinery on commit.
await (await sdk.createOffer({
  price,
  sellerDeposit: 0,                 // buyer doesn't set seller's stake — seller commits whatever they want covered
  buyerCancelPenalty: 0,            // typically 0 for buyer-initiated
  quantityAvailable: 1,
  exchangeToken,
  metadataUri,
  metadataHash,
  validFromDateInMS: Date.now(),
  validUntilDateInMS: Date.now() + 7 * 24 * 60 * 60 * 1000,
  voucherRedeemableFromDateInMS: Date.now(),
  voucherRedeemableUntilDateInMS: 0,
  voucherValidDurationInMS: 14 * 24 * 60 * 60 * 1000,
  disputeResolverId,
  agentId: 0,
  feeLimit: 0,
  creator: 1, // 1 = BUYER (0 = SELLER)
})).wait()
```

```ts twoslash [MCP]
// @noErrors
// Deposit + create flow via MCP (each returns an unsigned tx)
await mcp.depositFunds({ configId, signerAddress, accountId: buyerId, tokenAddress: exchangeToken, amount: price })
// then sign + broadcast …
await mcp.createOffer({ configId, signerAddress, offer: { /* …, creator: 1 */ }, /* …, agentId: 0, feeLimit: 0 */ })
```
:::

## Seller side: accept and commit

The seller calls `commitToBuyerOffer` with the offer ID plus the parameters the buyer couldn't set: which collection to mint into, royalty info, mutualizer (if any). The seller's deposit is encumbered at this step; the buyer's price (already in their treasury) is encumbered too.

:::code-group

```ts twoslash [SDK]
// @noErrors
await (await sdk.commitToBuyerOffer(offerId, {
  collectionIndex: 0,
  royaltyInfo: {
    recipients: ["0x0000000000000000000000000000000000000000"], // seller treasury (default)
    bps: [250],
  },
  mutualizerAddress: "0x0000000000000000000000000000000000000000", // self-mutualised
})).wait()
```

```ts twoslash [MCP]
// @noErrors
await mcp.commitToBuyerOffer({
  configId,
  signerAddress,
  offerId,
  sellerParams: {
    collectionIndex: 0,
    royaltyInfo: { recipients: [/* … */], bps: [/* … */] },
    mutualizerAddress: "0x0000000000000000000000000000000000000000",
  },
})
```
:::

This emits `SellerCommitted`, sets the offer's `sellerId`, and mints the voucher to the buyer. From the buyer's wallet it looks the same as a normal commit.

## Cancelling unmatched offers

If the validity window closes without any seller committing, the buyer can withdraw the deposit back from their treasury via `withdrawFunds`. No void step is needed — buyer-initiated offers go stale automatically.

For non-listed (private) buyer-initiated offers signed off-chain via `FullOffer`, use `voidNonListedOffer` (and the batch variant) to mark the hash as voided so it can't subsequently be matched.

## Discovery patterns

The protocol doesn't run the offer board. Common discovery channels:

- **XMTP** — buyer posts offer metadata + offer ID to a known topic; seller agents subscribe.
- **Custom RFQ board** — your own server indexes buyer offers; sellers poll.
- **Discord / forum** — humans hand-shake; one of them creates the offer.
- **Agent registry** — buyer agents announce demand, seller agents respond. See [Build for AI agents → Agent registry](/agents/registry).

The protocol only enforces "first seller to call `commitToBuyerOffer` wins" — it's a closed auction by default, plus whatever you layer on top.

## Common gotchas

- **Buyer must pre-fund.** Unlike seller-initiated offers, the buyer's price has to sit in their treasury before any seller can commit. Forgetting to deposit means sellers' commit attempts revert.
- **Royalties belong to the seller.** The buyer can't pre-set royalty recipients — that's a seller-side configuration. Buyers who care should ask sellers to commit with specific terms off-chain before submitting.
- **`commitToConditionalOffer` is not supported** for buyer-initiated offers — gating doesn't make sense in the inverted direction.
- **Price-discovery is not supported.** Buyer-initiated means static-priced. For dynamic pricing run a normal seller-side auction.
- **Quantity > 1** lets multiple sellers commit against the same buyer offer; each gets their own exchange. Useful for "I want 10 of these"; less common.

## Related

- [Build for AI agents](/agents) — buyer-initiated is the dominant flow for agent-to-agent commerce.
- [Concepts → Funds, escrow & payouts](/concepts/funds) — money flow under inversion.
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `ExchangeCommitFacet.commitToBuyerOffer`.

---

# Cancel / revoke

URL: https://www.bosonprotocol.io/docs/build/buyers/cancel

> How a buyer cancels (with penalty) and how a seller revokes (returning the buyer's price and forfeiting the seller deposit).

# Cancel / revoke

Two ways to back out of a `COMMITTED` exchange:

- **Buyer cancels** via `cancelVoucher` — buyer loses `buyerCancelPenalty`, gets the rest back. Seller keeps the cancel penalty.
- **Seller revokes** via `revokeVoucher` — buyer gets full refund; seller forfeits their `sellerDeposit` to the buyer.

Either ends the exchange.

:::code-group

```ts twoslash [SDK — buyer cancels]
// @noErrors
await (await sdk.cancelVoucher(exchangeId)).wait()
```

```ts twoslash [SDK — seller revokes]
// @noErrors
await (await sdk.revokeVoucher(exchangeId)).wait()
```

```ts twoslash [MCP]
// @noErrors
// buyer
await mcp.cancelVoucher({ configId, signerAddress, exchangeId })
// seller
await mcp.revokeVoucher({ configId, signerAddress, exchangeId })
```
:::

## When to use

- **Buyer cancel**: you changed your mind before redeeming. Accept the penalty.
- **Seller revoke**: you can't fulfill (out of stock, wrong info, fraud suspicion). Honor the buyer.
- **Neither**: don't cancel during an active dispute — the dispute machine takes over.

## Common gotchas

- **Cancel only works in `COMMITTED`.** After redemption, use the [dispute](./raise-dispute) path.
- **Revoke is a real cost to the seller.** Use sparingly. Track revoke rate as a quality signal in your internal ops.

## Next

- [Exchange state machine](/concepts/exchange-state-machine).
- [Raise a dispute](./raise-dispute).

---

# Commit to an offer

URL: https://www.bosonprotocol.io/docs/build/buyers/commit

> The core buyer action — approve the token if needed, then call commitToOffer.

# Commit to an offer

Committing to an offer transfers the buyer's price into escrow, mints a voucher (rNFT) to the buyer's wallet, and creates an `exchangeId`. The exchange starts in the `COMMITTED` state.

For ERC-20 offers, the buyer must first approve the Diamond to spend the token — or use one of the [token-auth meta-tx variants](/concepts/signing#token-auth-meta-tx) to combine approval and commit in one signed envelope.

## ERC-20 commit (two steps)

:::code-group

```ts twoslash [SDK]
// @noErrors
// 1. Approve the token (skip if you've already approved >= amount).
//    First arg is the ERC-20 token address, not the offerId.
await (await sdk.approveExchangeToken(exchangeTokenAddress, /* amount */ "1000000")).wait()

// 2. Commit. Signature is commitToOffer(offerId, overrides?); the buyer is the signer.
const tx = await sdk.commitToOffer(offerId)
const receipt = await tx.wait()
const exchangeId = sdk.getCommittedExchangeIdFromLogs(receipt.logs)
```

```ts twoslash [MCP]
// @noErrors
// 1. Approve (returns unsigned tx)
const { unsignedTx: approveTx } = await mcp.approveExchangeToken({
  configId: "production-137-0",
  signerAddress: wallet.address,
  offerId,
  amount: "1000000",
})
await mcp.sendSignedTransaction({
  chainId: 137,
  signedTx: await wallet.signTransaction(approveTx),
})

// 2. Commit
const { unsignedTx: commitTx } = await mcp.commitToOffer({
  configId: "production-137-0",
  signerAddress: wallet.address,
  buyer: wallet.address,
  offerId,
})
await mcp.sendSignedTransaction({
  chainId: 137,
  signedTx: await wallet.signTransaction(commitTx),
})
```
:::

## Native-token commit (one step)

If the offer's `exchangeToken` is `address(0)`, no approval — attach `msg.value`:

```ts twoslash
// @noErrors
const tx = await sdk.commitToOffer(offerId, { value: offer.price })
```

## Gas-less commit (meta-tx)

Use a [meta-transaction](/concepts/signing) to have someone else pay gas:

```ts twoslash
// @noErrors
const signedMetaTx = await sdk.metaTx.signMetaTxCommitToOffer({
  buyer: wallet.address,
  offerId,
})
await sdk.metaTx.relayMetaTransaction(signedMetaTx)
```

For the token-auth meta-tx flow (single-signature approve + commit), see [Recipes → Gas-less commit](/recipes/gasless-commit) and [Recipes → ERC-20 approve + commit](/recipes/erc20-commit).

## Atomic commit-and-redeem

If you want to commit and redeem in one transaction (typical for digital goods), see [Atomic commit-and-redeem](./atomic-commit-redeem).

## Common gotchas

- **Approve > price.** Approve more than `offer.price` to allow for multiple commits without re-approving each time.
- **Don't commit to a `validUntilDate`-expired offer.** The tx will revert with `OfferHasExpired`.
- **Token-gated offers require holding the gating token at commit time.** If you don't, the tx reverts with `CannotCommit`.
- **Indexing lag after commit.** Wait for `waitForGraphNodeIndexing(receipt.blockNumber)` before reading `getExchanges`.

## Next

- [Redeem a voucher](./redeem).
- [Cancel / revoke](./cancel).
- [Recipes → ERC-20 approve + commit](/recipes/erc20-commit).

---

# Buy via the Boson dApp

URL: https://www.bosonprotocol.io/docs/build/buyers/dapp

> The no-code path to buying on Boson — browse, commit, redeem, dispute through the hosted web UI.

# Buy via the Boson dApp

The simplest way to buy on Boson without writing code. Open [bosonapp.io](https://bosonapp.io/), connect a wallet, browse offers, commit, redeem.

## 1. Connect a wallet

MetaMask, WalletConnect, or any EIP-1193 provider. The dApp prompts you to switch to the right chain — currently Polygon for production. See [Concepts → Networks & ConfigIds](/concepts/networks-and-configids) for the full list.

## 2. Browse offers

Three entry points:

- **All sellers** — the dApp's main marketplace view.
- **Direct seller URL** — `bosonapp.io/#/store/<sellerId>` or a seller's custom storefront (see [Sellers → Sell via the Boson dApp → Storefront](/build/sellers/dapp#3-run-a-storefront-optional)).
- **Direct offer URL** — shared from search, social, or a partner site.

Token-gated offers display a lock icon. Hover or click to see what token / balance is required.

## 3. Commit

1. Click **Commit** on an offer.
2. If it's an **ERC-20 offer**, the dApp prompts an **Approve** transaction first (granting the Diamond an allowance). If you've already approved enough, this step is skipped.
3. **Commit** — your wallet pays `offer.price`. The dApp builds and broadcasts the transaction.
4. The dApp mints you an **rNFT (voucher)** which appears in your wallet. The exchange is now in `COMMITTED` state.

If anything reverts ("offer voided", "sold out", "gating condition not met"), the dApp surfaces a friendly message.

For the code equivalent: [Build → Buyers → Commit to an offer](./commit).

## 4. Wait for delivery → Redeem

When the goods arrive (physical), or when you're ready (digital), come back to the dApp and click **Redeem** on your exchange.

The dApp may prompt you for delivery info on this step (shipping address, email) which it sends to the seller via XMTP.

Redeeming transitions the exchange to `REDEEMED` and starts the dispute window. The voucher (rNFT) is burned.

## 5. Optional — raise a dispute

If the goods aren't right, within the dispute window:

1. **Redeem first** (you can't dispute an unredeemed exchange — use **Cancel** instead).
2. Open the exchange → **Raise dispute**.
3. The dApp guides you through mutual resolution (offer a `buyerPercent`), then escalation if needed.

See [Concepts → Dispute state machine](/concepts/dispute-state-machine) and [Build → Buyers → Raise a dispute](./raise-dispute).

## When to graduate to code

- You're buying programmatically — for an agent, a procurement system, a bot.
- You need scripted retries / idempotency.
- You want to bridge from another wallet system (HSM, MPC, smart account).

Switch to [Tooling → Core SDK](/tooling/core-sdk) or [Tooling → MCP / agent stack](/tooling/mcp).

---

# Discover offers

URL: https://www.bosonprotocol.io/docs/build/buyers/discover

> Query the subgraph for offers — by seller, by token, by state, by metadata.

# Discover offers

Buyers (and agents acting on their behalf) find offers by querying the Boson subgraph. The SDK and MCP both wrap subgraph queries with TypeScript types.

:::code-group

```ts twoslash [SDK]
// @noErrors
// All offers for one seller (use the seller's numeric id; the subgraph schema
// doesn't accept a nested `seller_` path with admin filter).
const offers = await sdk.getOffers({
  where: { sellerId },
  first: 50,
})

// Offers in a given price range and token
const cheap = await sdk.getOffers({
  where: {
    exchangeToken: USDC_ADDRESS,
    price_lt: "10000000",         // < 10 USDC
    voided: false,
  },
  orderBy: "createdAt",
  orderDirection: "desc",
})
```

```ts twoslash [MCP]
// @noErrors
const { offers } = await mcp.getOffers({
  configId: "production-137-0",
  where: {
    exchangeToken: USDC_ADDRESS,
    price_lt: "10000000",
    voided: false,
  },
  first: 50,
})
```
:::

## Search and faceted filtering

For full-text or faceted search across offers (by title, attributes, seller name), use the [Search mixin](/reference/core-sdk/search) (SDK) or higher-level marketplace queries.

## Indexing lag

The subgraph lags 1–3 blocks behind chain. An offer created _just now_ may not appear in `getOffers` for a few seconds. See [Eventing & indexing](/concepts/eventing).

## Common gotchas

- **The subgraph stores derived states.** Filter on `voided: false` and `validUntilDate_gt: <now>` to get only active offers.
- **`first` is capped** (typically at 1000). Paginate via `skip` or `id_gt`.
- **Querying by metadata fields** requires they be indexed — title, description, attributes — but not every custom field. See [Reference → Subgraph queries](/reference/subgraph) for the indexed schema.

## Next

- [Commit to an offer](./commit).
- [Reference → Core SDK → Marketplace mixin](/reference/core-sdk/marketplace).

---

# Raise a dispute

URL: https://www.bosonprotocol.io/docs/build/buyers/raise-dispute

> When the goods aren't right — raise, attempt mutual resolution, escalate if needed.

# Raise a dispute

After redemption, if the goods aren't what was promised, the buyer has a dispute window to raise a dispute. The exchange transitions to `DISPUTED` and the [dispute state machine](/concepts/dispute-state-machine) takes over.

:::code-group

```ts twoslash [SDK]
// @noErrors
await (await sdk.raiseDispute(exchangeId)).wait()
```

```ts twoslash [MCP]
// @noErrors
const { unsignedTx } = await mcp.raiseDispute({
  configId: "production-137-0",
  signerAddress: wallet.address,
  exchangeId,
})
```
:::

## Mutual resolution

The simplest path is mutual: buyer and seller agree on a `buyerPercent` (0–100) of the escrow that goes to the buyer. Both sign an EIP-712 typed-data envelope; whichever submits the tx attaches both sigs.

See [Recipes → Mutual dispute resolution](/recipes/mutual-dispute) for the full flow.

## Escalation

If mutual resolution doesn't happen within the resolution window, the buyer can escalate. The dispute resolver then decides binding `buyerPercent`, takes their fee, and the exchange terminates.

```ts twoslash
// @noErrors
await sdk.escalateDispute(exchangeId)
```

## Retracting

The buyer can retract at any time before resolution / escalation. The exchange terminates with the seller getting everything (price + deposit).

```ts twoslash
// @noErrors
await sdk.retractDispute(exchangeId)
```

## Common gotchas

- **The dispute window starts at redemption.** Not at commit. Watch `disputeDuration` on the offer.
- **Mutual sigs require both EIP-712 typed-data signatures to match.** Use the SDK / MCP helpers; don't hand-build.
- **You can't dispute a non-redeemed exchange.** Use [cancel](./cancel) instead.

## Next

- [Dispute state machine](/concepts/dispute-state-machine).
- [Build → Dispute Resolvers](/build/dispute-resolvers).
- [Recipes → Mutual dispute resolution](/recipes/mutual-dispute).

---

# Redeem a voucher

URL: https://www.bosonprotocol.io/docs/build/buyers/redeem

> Signal that you've received (or are ready to receive) the goods. Starts the dispute window.

# Redeem a voucher

Redemption is the buyer's signal that they want the goods. It transitions the exchange from `COMMITTED` to `REDEEMED` and starts the dispute window. After the dispute window closes (and no dispute was raised), anyone can call `completeExchange` to release the seller's earnings.

:::code-group

```ts twoslash [SDK]
// @noErrors
await (await sdk.redeemVoucher(exchangeId)).wait()
```

```ts twoslash [MCP]
// @noErrors
const { unsignedTx } = await mcp.redeemVoucher({
  configId: "production-137-0",
  signerAddress: wallet.address,
  exchangeId,
})
// sign + broadcast
```
:::

## When to redeem

- **Digital goods**: immediately after commit (or use [atomic commit-and-redeem](./atomic-commit-redeem)).
- **Physical goods**: when you receive the package. Until you redeem, you can [cancel](./cancel) (with penalty) or wait out the voucher window (price refunded, seller deposit kept by seller).

## Common gotchas

- **Don't redeem before you have the goods (physical).** Once redeemed, you can only [raise a dispute](./raise-dispute) within a fixed window.
- **The voucher (rNFT) is burned on redeem.** You'll lose secondary-market resale value.
- **Redemption fires `VoucherRedeemed`** — this is what the seller's fulfillment system listens to. See [Handle redemption](/build/sellers/handle-redemption).

## Next

- [Raise a dispute](./raise-dispute).
- [Cancel / revoke](./cancel).

---

# Sequential commit

URL: https://www.bosonprotocol.io/docs/build/buyers/sequential-commit

> Secondary-market resale through the protocol — full buyer protection chained across resellers, with perpetual royalty payouts.

# Sequential commit

A normal Boson voucher (rNFT) can be resold on any ERC-721 marketplace, but the protocol doesn't see those resales. If the original seller fails to deliver, escrow only covers the original price — secondary buyers who paid more take a loss.

Sequential commit solves this by routing secondary sales through the protocol via `sequentialCommitToOffer`. Each resale tops up the escrow with the price difference, so every buyer in the chain is protected up to what they actually paid. Royalties for each resale are recorded and paid out at finalisation. The protocol becomes the canonical secondary marketplace for redeemable vouchers.

This is a **buyer-side** action: a new buyer is committing to an existing exchange, taking ownership from the previous holder. The pricing happens through the same [price-discovery](/build/sellers/price-discovery) machinery used for primary sales — Ask, Bid, and Wrapper flows all work.

## Why it matters for buyers

- **Pay what you mean to pay.** Buy a voucher on a secondary market and your protection scales with your purchase price, not the original.
- **Royalty enforcement is on-chain.** Every resale recorded in the protocol pays the offer's royalty recipients automatically — no marketplace-by-marketplace tweaking.
- **The voucher behaves the same** post-commit. Redeem, dispute, complete all work as normal.

## How it works

::::steps

### Exchange in `COMMITTED` state, owned by reseller A

Where _reseller A_ is the original buyer or a prior resale buyer.

### `sequentialCommitToOffer(newBuyer, exchangeId, PriceDiscovery)`

The new buyer (or someone on their behalf) calls into the protocol with an `Ask | Bid | Wrapper` price-discovery payload.

### Diamond executes the hop

1. Resolve the price via the external price-discovery contract.
2. Compute the escrow delta — new money locked vs. already locked.
3. Pull the delta from the new buyer.
4. Release the prior price to the previous holder (minus protocol fees, royalties, and the cancellation-penalty cap).
5. Transfer the voucher to the new buyer.
6. Record `(price, fees, royalty recipients)` for this hop so finalisation pays everyone fairly.

### Exchange remains in `COMMITTED` state, now owned by newBuyer

The redemption clock is unchanged; the new buyer can redeem / dispute / complete as normal.

::::

If the new price is higher than the previous price, the **delta** is locked in escrow and the reseller's profit (after fees / royalties / capped buyer-cancellation-penalty) is released immediately. If the new price is equal or lower, **no additional escrow** is needed — the reseller just gets the secondary price and the protocol records the hop. Either way, on the worst-case finalisation (e.g. original seller revokes), every party gets reimbursed to their net cost basis.

## When to use

- **You're buying a voucher second-hand** and want full protocol protection.
- **You're building a secondary marketplace for Boson vouchers** — route trades through `sequentialCommitToOffer` instead of plain ERC-721 transfers.

For a sale that doesn't route through the protocol (e.g. a normal `transferFrom`), buyer protection stays at the original price level. That's not a bug — the protocol can't see what it can't see.

## Doing it from code

The sequential-commit surface mirrors price discovery. Use the same `PriceDiscovery` struct (`side`, `priceDiscoveryContract`, `priceDiscoveryData`, etc.); the only difference is the entry point and the identifier (exchange ID, not offer ID).

:::code-group

```ts twoslash [SDK]
// @noErrors
// At the current Core SDK version, there is no `sdk.sequentialCommitToOffer`
// helper. Build the call against the Diamond's `IBosonSequentialCommitHandler`
// facet via ethers — see Reference → Contracts → Facets.

import type { PriceDiscoveryStruct } from "@bosonprotocol/common"
import IBosonSequentialCommitHandler from "@bosonprotocol/common/dist/cjs/abis/IBosonSequentialCommitHandler.json"

const pd: PriceDiscoveryStruct = {
  price: secondaryPrice,
  side: 0, // Ask
  priceDiscoveryContract: SEAPORT_ADDRESS,
  conduit: SEAPORT_CONDUIT_ADDRESS,
  priceDiscoveryData: encodedFulfilmentCalldata,
}

const diamond = new ethers.Contract(DIAMOND_ADDRESS, IBosonSequentialCommitHandler, signer)
await (await diamond.sequentialCommitToOffer(
  newBuyerAddress,
  exchangeId,
  pd,
  { value: pd.price }, // for native-token offers
)).wait()
```

```solidity [Solidity]
interface IBosonSequentialCommitHandler {
    function sequentialCommitToOffer(
        address payable _buyer,
        uint256 _exchangeId,
        BosonTypes.PriceDiscovery calldata _priceDiscovery
    ) external payable;
}
```
:::

The reseller must approve the protocol to pull the voucher (Bid / Wrapper) or list it on the price-discovery contract in advance (Ask). See [Price discovery](/build/sellers/price-discovery) for the per-side mechanics — the rules are identical.

## Batch expiration (anyone can call)

A buyer who never redeems and never disputes lets the voucher expire silently. To clean up these dead exchanges and release any locked funds, anyone can run the expiration tools:

| Tool | When it applies |
| --- | --- |
| `expire_dispute` / `expire_dispute_batch` (MCP) / `expireDispute` (SDK) | Disputes that have aged out of the resolution window with no action |
| `expire_escalated_dispute` (MCP) / `expireEscalatedDispute` (SDK) | Escalated disputes where the dispute resolver didn't act before the response window closed |

These are idempotent — running them on an already-expired exchange is a no-op. Gas is paid by the caller. They're useful for marketplace operators and DR ops who want their finalisation backlog cleared.

## Finalisation math

At final state (`COMPLETED`, `DISPUTED → RESOLVED`, etc.) the protocol pays out:

1. Original seller — based on the latest sale price, minus protocol fee, agent fee, royalties, and any buyer-cancellation-penalty cap.
2. Each prior reseller — the difference between what they were paid at their hop and what they should keep given the final state, with royalties always paid for every hop the voucher passed through.
3. Royalty recipients — sum of each hop's contribution.
4. Final buyer — whatever's left if the seller failed (revoked, lost dispute).

## Common gotchas

- **Capital efficiency.** The protocol locks only the _minimum_ delta needed. If price stays flat or drops, no extra capital required.
- **Royalties paid at finalisation, not at each hop.** Even though resale records the recipient list, the actual transfer happens once at the end. Designers of secondary marketplaces that expect immediate royalty payout should plan for this.
- **Vouchers can't be sequentially committed across the dispute boundary.** Once `DISPUTED`, secondary resale via the protocol is closed — the next buyer would inherit the dispute, which is too messy.
- **Off-protocol transfers still work** (plain ERC-721 `transferFrom`) but bypass all this machinery — the new holder gets only the original seller's escrow as protection.

## Related

- [Sellers → Price discovery](/build/sellers/price-discovery) — sequential commit reuses the same machinery.
- [Sellers → Royalties](/build/sellers/royalties) — royalty recipients are paid per hop at finalisation.
- [Concepts → Exchange state machine](/concepts/exchange-state-machine).
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `SequentialCommitHandlerFacet`.

---

# Build — Dispute Resolvers

URL: https://www.bosonprotocol.io/docs/build/dispute-resolvers

> Register as a third-party arbiter, set fees, and resolve / decide / refuse disputes.

# Build — Dispute Resolvers

A **dispute resolver (DR)** is a third party — a person, multisig, DAO, or external arbitration system — that arbitrates disputed exchanges in exchange for a fee.

You register on-chain, configure your supported chains × tokens × fees, optionally restrict which sellers can use you, and then your job is to respond when disputes are escalated.

## Tasks

1. [Register & configure fees](./dispute-resolvers/register) — one-time on-chain setup.
2. [Decide / refuse](./dispute-resolvers/decide) — handle escalated disputes.
3. [DR fee mutualizer](./dispute-resolvers/fee-mutualizer) — pool DR fees across many offers so sellers aren't exposed to one-shot escalation costs.

## Reading list

- [Dispute state machine](/concepts/dispute-state-machine).
- [Reference → Core SDK → Disputes mixin](/reference/core-sdk/disputes).
- [Reference → MCP tools](/reference/mcp-tools) — dispute tools section.

---

# Decide / refuse

URL: https://www.bosonprotocol.io/docs/build/dispute-resolvers/decide

> Adjudicate an escalated dispute or refuse to.

# Decide / refuse

When a dispute is escalated to you, you have until the offer's `escalationResponsePeriod` to:

- **Decide**: assign a `buyerPercent` (0–10000 basis points). Buyer gets that share of escrow; seller gets the rest; you collect your fee.
- **Refuse**: send escrow back to the buyer (including the DR fee), seller deposit back to seller. You collect nothing.

:::code-group

```ts twoslash [SDK]
// @noErrors
await sdk.decideDispute(exchangeId, /* buyerPercent */ 6000)  // 60% to buyer
// or
await sdk.refuseEscalatedDispute(exchangeId)
```

```ts twoslash [MCP]
// @noErrors
await mcp.decideDispute({
  configId: "production-137-0",
  signerAddress: wallet.address,
  exchangeId,
  buyerPercent: "6000",
})
// or
await mcp.refuseEscalatedDispute({ configId, signerAddress, exchangeId })
```
:::

## When to refuse

- You can't verify the buyer's claim.
- The seller has gone dark and you can't gather evidence.
- The dispute is outside your jurisdiction / scope.

## Time pressure

If you don't act before `escalationResponsePeriod` expires, the dispute auto-resolves: buyer gets full escrow, you collect nothing. This is harsher than refusing — _refuse explicitly_ if you don't intend to decide.

## Next

- [Dispute state machine](/concepts/dispute-state-machine).
- [Reference → Core SDK → Disputes mixin](/reference/core-sdk/disputes).

---

# DR fee mutualizer

URL: https://www.bosonprotocol.io/docs/build/dispute-resolvers/fee-mutualizer

> External insurance pool that covers dispute-resolver fees on behalf of sellers, so buyers can escalate without ruining the seller's economics.

# DR fee mutualizer

A dispute resolver (DR) charges a fee when an exchange is escalated. Two naïve options for who pays:

- **Seller pays.** Then any buyer can grief the seller by escalating frivolously.
- **Buyer pays.** Then buyers are discouraged from escalating legitimate complaints.

Neither is good. The DR fee mutualizer introduces a third option: an external **mutualizer** contract that pools DR fees. A seller pays a small premium per offer (or per-exchange-cap-per-period), and the mutualizer pays the DR fee from the pool if escalation happens. Buyers can escalate freely; sellers don't bear the unilateral risk; the mutualizer operator earns a margin via the premium spread.

The protocol speaks a minimal interface (`IDRFeeMutualizer`) — `isSellerCovered`, `requestDRFee`, `returnDRFee`. Anyone can deploy a mutualizer; the reference implementation `IDRFeeMutualizerClient` adds agreement management on top. A seller picks a mutualizer per offer at creation time (or self-mutualises by setting the address to zero).

## Flow

```mermaid
flowchart TD
    S1[1. seller + mutualizer agree on terms off-chain]
    S1 --> S2["2. mutualizer.newAgreement(...)<br/><i>admin-side</i>"]
    S2 --> S3["3. seller calls payPremium(agreementId, ...)<br/><i>agreement becomes Active</i>"]
    S3 --> S4["4. seller createOffer with<br/>DRParameters.mutualizerAddress = mutualizerAddress"]
    S4 --> EX["…buyer commits, exchange runs…"]
    EX --> H{Outcome}
    H -->|"5a. happy path<br/>(completes or mutually resolved)"| HA["protocol calls returnDRFee(exchangeId, feeAmount)<br/><i>full refund</i>"]
    H -->|5b. escalated, DR decides| HB["protocol calls returnDRFee(exchangeId, 0)<br/><i>fee retained for DR; fee paid to DR</i>"]
    H -->|5c. escalated, DR refuses| HC["protocol calls returnDRFee(exchangeId, feeAmount)<br/><i>refund; buyer gets escalation deposit back too</i>"]
```

`requestDRFee` is called by the protocol at commit time; if the mutualizer can't cover, the commit reverts (no buyer/seller funds get locked; no voucher issued; safe failure mode).

## Self-mutualised offers

Setting `DRParameters.mutualizerAddress` to `address(0)` means the seller bears the DR fee themselves out of their treasury. This is the default and the right call for low-DR-fee offers (e.g. canonical free DR), high-trust contexts, or when no mutualizer is available.

Most offers in the protocol today are self-mutualised with `feeAmount = 0`, so the question is mainly academic until you use a paid DR.

## When to use

- **High-value offers** with a paid DR — capped per-exchange fee + amortised premium is cheaper than the worst-case escalation.
- **Marketplaces with broad seller bases** — operators can run a mutualizer as a service.
- **Sellers with predictable dispute rates** — the math works out if your actual dispute rate is below the mutualizer's pricing.

## Building a mutualizer

Implement `IDRFeeMutualizer` (the minimal interface) at a contract you control. You can also implement the optional `IDRFeeMutualizerClient` to expose admin/seller-facing agreement management — strongly recommended for ecosystem interop:

```solidity
interface IDRFeeMutualizer is IERC165 {
    function isSellerCovered(
        uint256 sellerId,
        uint256 feeAmount,
        address tokenAddress,
        uint256 disputeResolverId
    ) external view returns (bool);

    function requestDRFee(
        uint256 sellerId,
        uint256 feeAmount,
        address tokenAddress,
        uint256 exchangeId,
        uint256 disputeResolverId
    ) external returns (bool success);

    function returnDRFee(uint256 exchangeId, uint256 feeAmount) external payable;
}
```

The protocol calls `requestDRFee` from the address of `ProtocolDiamond`; verify the caller and revert on anyone else. `returnDRFee` is also Diamond-only.

For native-currency agreements, `returnDRFee` sends `msg.value == feeAmount`. For ERC-20s it pulls via `transferFrom` (so your mutualizer needs Diamond as an approved spender), or the Diamond pushes via `transfer` — implementations vary; check the reference.

`IDRFeeMutualizerClient` extends with:

- `deposit / withdraw` — fund the pool.
- `newAgreement / voidAgreement / payPremium` — agreement lifecycle.
- `getAgreement / getAgreementId` — reads.

Each agreement specifies a seller, exchange-token, dispute-resolver triple (DR ID `0` = universal across all DRs), plus per-tx cap, total cap, time period, premium, and `refundOnCancel`. This shape covers the common business models without locking implementations into it.

## Configure on an offer

```ts twoslash
// @noErrors
await sdk.createOffer({
  // …offer fields…
  // DRParameters used to be just `disputeResolverId`; mutualizerAddress was added later.
  drParameters: {
    disputeResolverId,
    mutualizerAddress: MY_MUTUALIZER_ADDRESS, // or 0x0 for self-mutualised
  },
})
```

Switching mutualizers later is allowed (mutualizer address is one of the few mutable offer fields). Existing exchanges keep their original mutualizer — the change only affects future commits.

## Read coverage status before committing

A buyer or seller dApp should check whether the mutualizer will actually cover before letting the buyer commit, so the commit doesn't revert at the worst possible moment:

```ts twoslash
// @noErrors
const mutualizer = new ethers.Contract(mutualizerAddress, MUTUALIZER_ABI, provider)
const covered = await mutualizer.isSellerCovered(
  sellerId,
  drFeeAmount,
  exchangeToken,
  disputeResolverId,
)
if (!covered) showWarning("Seller's mutualizer is out of funds; commits will revert")
```

## Common gotchas

- **Pool drain risk.** If a popular mutualizer runs dry, every commit on every offer pointing at it reverts. Subscribe to balance events or fall back to self-mutualisation.
- **Premium economics.** A mutualizer pricing assumes a known dispute rate. Bad actors can stack escalations against a single covered seller. Limit per-seller exposure (`maxAmountPerTx`, `maxAmountTotal`).
- **Trust-bootstrapping.** A new mutualizer with no track record is a hard sell. Operators typically front the float themselves until premiums catch up.
- **One mutualizer, many sellers.** Pool the risk widely so the law of large numbers actually kicks in.
- **DR refusing arbitration returns the fee to the mutualizer (not the seller).** The seller's premium is the cost of the option; if the DR refuses, the option's value was the unused coverage.

## Related

- [Concepts → Dispute state machine](/concepts/dispute-state-machine).
- [Concepts → Funds, escrow & payouts](/concepts/funds).
- [Build → Dispute Resolvers → Register & configure fees](./register).
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) — `DRParameters`, fee paths.

---

# Register & configure fees

URL: https://www.bosonprotocol.io/docs/build/dispute-resolvers/register

> Create a dispute resolver entity and configure your per-token fees.

# Register & configure fees

A DR is registered with `createDisputeResolver`. After registration, configure the supported chains × tokens × fees and (optionally) a seller allowlist.

:::code-group

```ts twoslash [SDK]
// @noErrors
const tx = await sdk.createDisputeResolver({
  escalationResponsePeriodInMS: 7 * 24 * 60 * 60 * 1000,  // ms, like every other duration in the SDK
  assistant: wallet.address,
  admin: wallet.address,
  treasury: wallet.address,
  metadataUri: "ipfs://Qm…", // terms of service, contact, etc.
  fees: [
    { tokenAddress: USDC_ADDRESS, tokenName: "USDC", feeAmount: "0" },
    { tokenAddress: ethers.constants.AddressZero, tokenName: "ETH", feeAmount: "0" },
  ],
  sellerAllowList: [],  // empty = any seller may use this DR
})
```

```ts twoslash [MCP]
// @noErrors
// DR creation is currently SDK / on-chain only;
// the MCP get_dispute_resolvers tool lets you read them.
```
:::

The protocol now sets the `clerk` and `active` fields automatically (no longer takes them as input).

After creation, fees and allowlist can also be modified later:
- `sdk.addFeesToDisputeResolver(drId, [{ tokenAddress, tokenName, feeAmount }])`
- `sdk.addSellersToAllowList(drId, [sellerIds])` (or omit and accept any seller)

## Common gotchas

- **`escalationResponsePeriodInMS` is in milliseconds**, like other SDK duration fields.
- **You must supply at least one fee at creation.** Add more later via `addFeesToDisputeResolver`.
- **Fees are per-token.** Each chain × token combo must be added.
- **You can't retroactively change fees on existing offers.** Offers cache the DR fee at creation.

## Next

- [Decide / refuse](./decide).

---

# Build — Marketplace operators

URL: https://www.bosonprotocol.io/docs/build/marketplace

> Run a marketplace that aggregates sellers, surfaces offers, and earns a protocol agent fee.

# Build — Marketplace operators

If you run a storefront or aggregator that lists multiple sellers' offers, you're a **marketplace operator**. You don't sell yourself — you index and surface.

Optional but useful: register as a [protocol agent](/concepts/roles#protocol-agent) so each offer you facilitate pays you a percentage on completion.

## Tasks

1. [Search & discovery](./marketplace/search) — query and rank offers.
2. [Webhooks & events](./marketplace/webhooks) — react to on-chain state changes.
3. [Multi-chain surfaces](./marketplace/multi-chain) — aggregate across chains.
4. [Token-gated launches](./marketplace/token-gated) — restrict commits by token holdings.

## Reading list

- [Eventing & indexing](/concepts/eventing).
- [Roles → Protocol Agent](/concepts/roles#protocol-agent).
- [Reference → Core SDK → Marketplace mixin](/reference/core-sdk/marketplace).
- [Reference → Core SDK → Search mixin](/reference/core-sdk/search).

---

# Multi-chain surfaces

URL: https://www.bosonprotocol.io/docs/build/marketplace/multi-chain

> Aggregate Boson offers across Polygon, Mainnet, Base, Optimism, and Arbitrum.

# Multi-chain surfaces

Boson is deployed to multiple chains. Each chain has its own Diamond, its own subgraph, and its own seller / offer ID space. A marketplace that surfaces offers from multiple chains must index each independently and reconcile in its application layer.

## Pattern: one SDK instance per chain

```ts twoslash
// @noErrors
const chains = ["production-137-0", "production-8453-0", "production-42161-0"] as const

const sdks = Object.fromEntries(
  chains.map(c => [c, CoreSDK.fromDefaultConfig({
    web3Lib: readOnlyAdapter,
    envName: "production",  // matches the env prefix of each configId above
    configId: c,
  })]),
) as Record<typeof chains[number], CoreSDK>

async function getAllActiveOffers() {
  const results = await Promise.all(
    chains.map(c => sdks[c].getOffers({ where: { voided: false } })),
  )
  return results.flatMap((offers, i) => offers.map(o => ({ ...o, chain: chains[i] })))
}
```

## Display considerations

- **Show the chain on every offer card.** Users care.
- **Don't merge IDs across chains.** Always carry the `configId` alongside the offer ID.
- **Bridge currencies in the UI** — show USD-equivalent if the buyer's wallet is on a different chain than the offer.

## Common gotchas

- **A buyer on Polygon can't commit to an offer on Base** without bridging.
- **Subgraph health varies per chain.** Health-check each separately; route around a stale subgraph by reading from RPC.
- **Gas estimates vary wildly.** Mainnet > L2s by ~100×. Surface this in commit-button copy.

## Next

- [Networks & ConfigIds](/concepts/networks-and-configids).
- [Networks → Subgraph endpoints](/networks/subgraph).

---

# Search & discovery

URL: https://www.bosonprotocol.io/docs/build/marketplace/search

> Query, rank, and surface offers from the Boson subgraph.

# Search & discovery

The Core SDK's `Marketplace` and `Search` mixins layer on top of the subgraph to give you typed, paginated, faceted access to offers.

```ts twoslash
// @noErrors
// All active offers from any seller, sorted by created-at descending
const offers = await sdk.searchOffers({
  filter: {
    state: "ACTIVE",          // derived: voided=false, validUntilDate>now, qty>0
    exchangeToken: USDC_ADDRESS,
    priceRange: { min: "0", max: "100000000" },
  },
  sort: { field: "createdAt", order: "desc" },
  pagination: { first: 50, skip: 0 },
})

// Faceted aggregation — counts by seller
const facets = await sdk.facetOffers({
  facet: "seller",
  filter: { state: "ACTIVE" },
})
```

## Indexing & lag

All queries hit the [subgraph](/concepts/eventing) — 1–3 block lag. For real-time inventory checks (e.g. "can a buyer still commit?"), confirm `quantityAvailable` from the Diamond directly.

## Common patterns

- **Browse by category** — encode categories as `productV1.tags` in metadata; index in your own search service.
- **Rank by social signal** — combine subgraph data with off-chain signals (favorites, views) in your application layer.
- **"New" badge** — offers with `createdAt > now - 7d`.

## Next

- [Reference → Core SDK → Search mixin](/reference/core-sdk/search).
- [Reference → Subgraph queries](/reference/subgraph).

---

# Token-gated launches

URL: https://www.bosonprotocol.io/docs/build/marketplace/token-gated

> Restrict who can commit to an offer based on token holdings (ERC-20, ERC-721, ERC-1155).

# Token-gated launches

A token-gated offer attaches a `Condition` that the buyer's wallet must satisfy at commit time. Built into the protocol — no off-chain allow-listing required.

## Condition shape

```ts
{
  method: 0 | 1 | 2,           // 0=None, 1=Threshold, 2=TokenRange
  tokenType: 0 | 1 | 2,         // 0=ERC-20, 1=ERC-721, 2=ERC-1155
  tokenAddress: "0x…",
  tokenId: "<token id, for 721/1155>",
  threshold: "<min balance, for 20>",
  maxCommits: "1",              // per address
  gating: 0 | 1,                // 0=PerAddress, 1=PerTokenId
}
```

## Create a token-gated offer

```ts twoslash
// @noErrors
const tx = await sdk.createOfferWithCondition({
  offer: { /* …regular offer fields… */ },
  condition: {
    method: 1,                        // Threshold
    tokenType: 0,                     // ERC-20
    tokenAddress: USDC_ADDRESS,
    threshold: "100000000",           // must hold ≥ 100 USDC
    maxCommits: "1",
    gating: 0,                        // per address
  },
})
```

Or via MCP: `create_offer_with_condition`.

## Per-tokenId gating (drops)

For drops where each token in a collection gets one commit, use `gating: 1` (PerTokenId) with an ERC-721 / 1155 condition. Each `tokenId` can be used `maxCommits` times in total.

## Common gotchas

- **The condition is checked at commit time, not creation time.** If the buyer no longer holds the gating token at commit, the tx reverts.
- **`maxCommits` is per-address (or per-tokenId).** A buyer with `maxCommits = 1` can't commit a second time, even if they hold more tokens.
- **Condition enum naming.** "TokenRange" sometimes appears as "SpecificToken" in older SDK versions. Pin SDK version.

## Next

- [Reference → Core SDK → Groups mixin](/reference/core-sdk/groups).
- [Reference → MCP tools](/reference/mcp-tools) → `create_offer_with_condition`.
- [Recipes → Token-gated launch](/recipes/token-gated).

---

# Webhooks & events

URL: https://www.bosonprotocol.io/docs/build/marketplace/webhooks

> React to state changes — listen via RPC, the subgraph, or your own webhook server.

# Webhooks & events

Marketplace operators need to react to on-chain state changes — a new offer, a commit on a listed offer, a dispute, a redemption. Three eventing surfaces are available; see [Concepts → Eventing & indexing](/concepts/eventing) for the canonical reference.

## A simple webhook listener (RPC)

```ts twoslash
// @noErrors
import { ethers } from "ethers"
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"
import disputeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonDisputeHandler.json"

const diamond = new ethers.Contract(DIAMOND_ADDRESS, [...offerAbi, ...exchangeAbi, ...disputeAbi], provider)

const handlers: Record<string, (args: any) => Promise<void>> = {
  OfferCreated: async (args) => postToCRM("offer_created", args),
  BuyerCommitted: async (args) => postToCRM("buyer_committed", args),
  VoucherRedeemed: async (args) => postToCRM("voucher_redeemed", args),
  DisputeRaised: async (args) => postToCRM("dispute_raised", args),
}

for (const [evt, fn] of Object.entries(handlers)) {
  diamond.on(evt, (...args) => fn(args))
}
```

## Reorg-safe pattern

```
1. Receive event
2. dedupe = `${txHash}:${logIndex}`
3. if (alreadyProcessed(dedupe)) return
4. wait N confirmations  // 2-3 L2, 12+ L1
5. process
6. mark processed
```

See [Recipes → Webhook server](/recipes/webhook-server) for a full implementation.

## Subgraph polling

For lower-volume use cases, poll the subgraph every 30s:

```ts twoslash
// @noErrors
setInterval(async () => {
  const newOffers = await sdk.getOffers({
    where: { createdAt_gt: lastSeenCreatedAt.toString() },
    orderBy: "createdAt",
    orderDirection: "asc",
  })
  for (const o of newOffers) await process(o)
  lastSeenCreatedAt = newOffers.at(-1)?.createdAt ?? lastSeenCreatedAt
}, 30_000)
```

## Critical events for marketplace operators

| Event | Reason to listen |
| --- | --- |
| `OfferCreated` | Index for search; notify followers of seller |
| `OfferVoided` | Remove from search; refund pending displays |
| `BuyerCommitted` | Update inventory; notify seller; award protocol-agent fee |
| `VoucherRedeemed` | Trigger fulfillment; close pre-order list |
| `DisputeRaised` | Pause inventory; surface support flow |
| `ExchangeCompleted` | Update reputation / score; close order |

## Next

- [Concepts → Eventing & indexing](/concepts/eventing).
- [Recipes → Webhook server](/recipes/webhook-server).
- [Reference → Contracts → Events](/reference/contracts/events).

---

# Build — Royalty Recipients

URL: https://www.bosonprotocol.io/docs/build/royalty-recipients

> Receive a percentage of secondary-sale royalties on voucher (rNFT) trades.

# Build — Royalty Recipients

Royalty recipients are registered per-seller and earn a share of secondary-sale royalties whenever the voucher (rNFT) for an offer is resold on a marketplace that honors ERC-2981.

Set up by the seller via `addRoyaltyRecipients(sellerId, [{ recipient, minRoyaltyPercentage }])` ([SDK → Accounts mixin](/reference/core-sdk/accounts)).

:::info
Stub. Full content TBD — including: claim flow, secondary-marketplace compatibility matrix, and royalty splitter contract patterns.
:::

## Next

- [Sellers → Royalties](/build/sellers/royalties).

---

# Build — Sellers

URL: https://www.bosonprotocol.io/docs/build/sellers

> Everything a seller can do on Boson, organized by task. Each task page shows the snippet in your stack of choice.

# Build — Sellers

A **seller** is the entity that publishes offers. Every task below is the same regardless of which stack you're using — the only thing that changes is the snippet.

For each task, expand the **CodeGroup** to see the equivalent code in:
- **SDK** — TypeScript with `@bosonprotocol/core-sdk`.
- **MCP** — calling tools on the hosted MCP server.
- **Solidity** — direct on-chain (when applicable).

If you're not writing code at all, see [Sell via the Boson dApp](./sellers/dapp) or [Sell via WooCommerce](./sellers/woocommerce).

## Setup tasks

1. [Create a seller](./sellers/create-seller) — one-time on-chain registration.
2. [Manage funds](./sellers/manage-funds) — deposits, withdrawals, treasury.

## Publishing tasks

3. [Publish an offer](./sellers/publish-offer) — the core action.
4. [Bundles & variants](./sellers/bundles-variants) — group items.
5. [Royalties](./sellers/royalties) — secondary-sale revenue.
6. [Multi-collection](./sellers/multi-collection) — multiple voucher collections per seller.
7. [Pre-minted vouchers](./sellers/pre-minted-vouchers) — drops and limited editions.
8. [Price discovery](./sellers/price-discovery) — auctions and dynamic pricing.

## Operational tasks

9. [Handle redemption / deliver](./sellers/handle-redemption) — the fulfillment handoff.

## Non-code paths

10. [Sell via the Boson dApp](./sellers/dapp) — UI walkthrough.
11. [Sell via WooCommerce](./sellers/woocommerce) — plugin install and configuration.

## Prerequisites for every task

- A funded wallet on your target chain. See [Wallets & key management](/concepts/wallets).
- The right `configId` for your environment. See [Networks & ConfigIds](/concepts/networks-and-configids).
- A seller account on-chain. See [Create a seller](./sellers/create-seller).
- IPFS pinning configured if you're using PRODUCT_V1 metadata. See [The metadata pipeline](/concepts/metadata).

---

# Bundles & variants

URL: https://www.bosonprotocol.io/docs/build/sellers/bundles-variants

> Group multiple items into a single offer (BUNDLE metadata) and create offer variants for size / colour / SKU.

# Bundles & variants

A **bundle** ships multiple items together under a single offer; the buyer commits once and receives the whole set. A **variant** is one of several offers for the same product (e.g. small / medium / large t-shirt) grouped under a shared `productUuid`.

## Bundles

Use the `BUNDLE` metadata schema (`@bosonprotocol/metadata`). The bundle metadata lists each item with its own `productV1` payload plus an aggregate description. Reference: [The metadata pipeline](/concepts/metadata) and [Reference → Metadata schemas](/reference/metadata).

:::code-group

```ts twoslash [SDK]
// @noErrors
// Build a BUNDLE metadata object directly per the schema — there is no
// bundleMetadataFactory export. See Reference → Metadata schemas for the
// complete shape (required: schemaUrl, type: "BUNDLE", uuid, name,
// description, externalUrl, licenseUrl, image, attributes, items, seller).
const uuid = crypto.randomUUID()
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "BUNDLE" as const,
  uuid,
  name: "Hoodie + access pass",
  description: "Bundle: hoodie + 1-year Discord access",
  externalUrl: `https://example.com/${uuid}`,
  licenseUrl: `https://example.com/${uuid}/license`,
  image: "https://cdn.example.com/bundle.jpg",
  attributes: [
    { traitType: "Type", value: "Bundle" },
    { traitType: "Items", value: "2" },
  ],
  items: [
    { type: "ITEM_PRODUCT_V1", productV1: { title: "Hoodie", /* …product fields… */ } },
    { type: "ITEM_NFT", nft: { name: "Discord access pass", /* …nft fields… */ } },
  ],
  seller: { defaultVersion: 1, name: "Your brand", contactLinks: [{ tag: "email", url: "mailto:hi@example.com" }] },
}
const metadataUri = await sdk.storeMetadata(metadata)
await sdk.createOffer({ metadataUri, /* …rest */ })
```

```ts twoslash [MCP]
// @noErrors
const { metadataUri } = await mcp.storeBundleMetadata({
  configId: "production-137-0",
  uuid: crypto.randomUUID(),
  bundle: { /* … */ },
})
await mcp.createOffer({ /* … using metadataUri */ })
```
:::

## Variants

There's no special API for variants — you publish multiple offers that share the same `productUuid` in their metadata. The subgraph's `get_all_products_with_not_voided_variants` (MCP) / `getAllProductsWithNotVoidedVariants` (SDK) groups them for you.

```ts
// query all variant offers for a product
const products = await sdk.getAllProductsWithNotVoidedVariants({
  where: { productUuid: "<uuid>" },
})
```

## Common gotchas

- **Bundles are one offer, one exchange.** The buyer can't redeem one item from a bundle and dispute the other.
- **Variants are separate exchanges.** A buyer who wants two sizes commits twice.

## Next

- [Publish an offer](./publish-offer).
- [Reference → Metadata schemas](/reference/metadata).

---

# Create a seller

URL: https://www.bosonprotocol.io/docs/build/sellers/create-seller

> One-time on-chain registration. Mints the seller entity and the voucher (rNFT) collection.

# Create a seller

A seller account is a one-time on-chain registration. Every wallet that publishes offers needs one. It mints the seller entity and an associated voucher (rNFT) collection.

:::code-group

```ts twoslash [SDK]
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

const sdk = CoreSDK.fromDefaultConfig({
  web3Lib: new EthersAdapter(provider, wallet),
  envName: "production",
  configId: "production-137-0",
})

const tx = await sdk.createSeller({
  assistant: wallet.address,
  admin: wallet.address,
  treasury: wallet.address,
  contractUri: "ipfs://Qm…",     // OpenSea-style collection metadata URI
  royaltyPercentage: "0",        // basis points × 100 (0 = none)
  authTokenId: "0",              // "0" if not using auth tokens (admin field is enough)
  authTokenType: 0,              // 0 = None, 1 = Lens profile NFT
  metadataUri: "ipfs://Qm…",     // seller-level metadata
})
const receipt = await tx.wait()
await sdk.waitForGraphNodeIndexing(receipt.blockNumber)

const seller = (await sdk.getSellersByAddress(wallet.address))[0]
console.log("seller.id =", seller.id)
```

```ts twoslash [MCP]
// @noErrors
import { BosonMCPClient } from "@bosonprotocol/agentic-commerce/boson"

const mcp = new BosonMCPClient()
await mcp.connectToServer(process.env.BOSON_MCP_URL!)

const { unsignedTx } = await mcp.createSeller({
  configId: "production-137-0",
  signerAddress: wallet.address,
  // signerAddress is used as admin / assistant / treasury automatically.
  contractUri: "ipfs://Qm…",
  royaltyPercentage: "0",
  authTokenId: "0",
  authTokenType: 0,
  // Seller-metadata fields (kind, type, contactPreference, …) — see
  // Reference → MCP tools → create_seller for the full schema.
})

const signed = await wallet.signTransaction(unsignedTx)
const { txHash } = await mcp.sendSignedTransaction({ chainId: 137, signedTx: signed })

const { sellers } = await mcp.getSellersByAddress({
  configId: "production-137-0",
  wallet: wallet.address,
})
```

```solidity [Solidity]
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IBosonAccountHandler {
    struct Seller {
        uint256 id;
        address assistant;
        address admin;
        address clerk;
        address payable treasury;
        bool active;
        string metadataUri;
    }
    struct AuthToken { uint256 tokenId; uint8 tokenType; }
    struct VoucherInitValues { string contractURI; uint256 royaltyPercentage; bytes32 collectionSalt; }

    function createSeller(
        Seller calldata _seller,
        AuthToken calldata _authToken,
        VoucherInitValues calldata _voucherInitValues
    ) external;
}
```
:::

## Inputs explained

- `assistant` — the operational signer. Calls `createOffer`, `voidOffer`, etc.
- `admin` — privileged. Updates the seller's config. (When using auth tokens, set to `0x0…0` and use `authTokenId` / `authTokenType` instead.)
- `treasury` — recipient of offer proceeds. Can be different from assistant/admin.
- `contractUri` — IPFS URI for OpenSea-style collection metadata. Required, can be an empty placeholder.
- `royaltyPercentage` — basis points × 100 (so `500` = 5 %). For secondary-sale royalties.
- `authTokenId` — token id used as the admin auth token (e.g. a Lens profile id). `"0"` if not used.
- `authTokenType` — `0` (None) or `1` (Lens profile NFT).
- `metadataUri` — seller-level metadata (separate from `contractUri`, which is collection-level).

> The deprecated `clerk` role is no longer settable; the protocol now stores `address(0)` for it internally.

## What gets created

| Entity | What |
| --- | --- |
| Seller (on-chain) | `Seller` struct, retrievable by `getSellersByAddress(wallet)` |
| Voucher collection | A new ERC-721 contract; one per seller (or many with [multi-collection](./multi-collection)) |

## Common gotchas

- **Each wallet can only have one seller.** Attempting to call `createSeller` twice from the same `admin` reverts.
- **The treasury can be a smart contract.** Useful for routing funds through a multisig.
- **Setting `royaltyPercentage` here doesn't enforce it.** Royalty enforcement depends on the marketplace; the on-chain field is informational. See [Royalties](./royalties).

## Next

- [Publish an offer](./publish-offer).
- [Manage funds](./manage-funds).
- [Reference → Core SDK → Accounts mixin](/reference/core-sdk/accounts).

---

# Sell via the Boson dApp

URL: https://www.bosonprotocol.io/docs/build/sellers/dapp

> The no-code path to selling on Boson. Create a seller profile, list products, run a storefront — all through the hosted web UI.

# Sell via the Boson dApp

If you don't want to write code, the [Boson dApp](https://bosonapp.io/) is the no-code path. It wraps the same protocol the SDK uses, behind a UI. You connect a wallet, fill in forms, and hit confirm.

You'll do four things, in this order:

1. **Create a seller profile** — one-time on-chain setup.
2. **Initialize a communication channel** — XMTP, on first product.
3. **Start selling** — directly from your profile, or via a customized storefront.
4. **Manage sales via Seller Hub** — orders, redemptions, disputes.

## 1. Create a seller profile

Open [bosonapp.io](https://bosonapp.io/) and click **Sell on Boson**. The dApp will walk you through:

- **Wallet connect** — MetaMask, WalletConnect, etc.
- **Optional Lens profile link** — if you hold a [Lens](https://lens.xyz) profile, toggle **Link Lens Profile** at the top right. Your handle pre-populates. If you don't have one, you can skip or create one.
- **Brand details** — logo, cover, brand name (required); description, contact info, social links (recommended). Each image should be < 500 KB.
- **Communication method** — pick the default channel for buyers to reach you. **XMTP** is recommended for at least the initial delivery-address handoff; see [Concepts → Fulfillment channels](/concepts/fulfillment).
- **Royalties** — optionally set a secondary-sales royalty percentage. **This cannot be changed later.** See [Sellers → Royalties](./royalties).
- **Confirm** — sign the `Create Seller Account` message in your wallet.

This is `createSeller()` under the hood. See [Sellers → Create a seller](./create-seller) for the equivalent in code.

You can edit your profile later from the seller icon.

## 2. Create products

The dApp supports physical, phygital, and digital products, with optional variants. From the seller hub, click **Create Products**.

You do *not* need MATIC to pay gas — the dApp uses meta-transactions and subsidises gas for you. You'll just sign messages.

The flow walks you through:

1. **Product type** — physical / phygital / digital, single item or variants.
2. **Product information** — title, description, category, tags, attributes. Pick an existing category if you can; create a custom one only if truly novel.
3. **Additional information** — SKUs, brand, manufacturer model numbers, etc. Optional but useful for inventory management.
4. **Product images & video** — jpg / jpeg / png / gif / webp images, plus optional mp4 video.
5. **Core terms of sale**:
    - **Price** in any supported ERC-20 (or native MATIC). Listing in $BOSON waives the protocol fee.
    - **Quantity available**.
    - **Validity period** — the window during which buyers can commit.
    - **Redemption period** — how long after commit the buyer can redeem.
    - **Optional token-gating** — see below.
6. **Token-gated offers** (optional) — restrict commits to holders of a specific ERC-20, ERC-721, or ERC-1155 token. See [Token gating](#token-gating) below and [Recipes → Token-gated launch](/recipes/token-gated).
7. **Terms of exchange** — the contractual policy (currently one canonical policy is offered), buyer cancellation penalty, seller deposit, dispute resolver, dispute period.
8. **Shipping info** — regions, expected delivery time, return period, optional parcel size & weight.
9. **Confirm** — preview, initialize XMTP (first product only), sign the on-chain transaction.

The first time you create a product, you'll initialize XMTP. You'll see **XMTP: Create Identity** in your wallet first, then **XMTP: Enable Identity** once per session afterwards. Both are message signatures, not transactions. See [xmtp.org/docs](https://xmtp.org/docs/concepts/account-signatures) for what's happening.

Once submitted, the offer is on-chain — **you can't edit it later**. If anything's wrong, void and recreate.

## 3. Run a storefront (optional)

If you sell more than a couple of items, a **storefront** is a branded page that lists your offers (and optionally others') with your colours and fonts.

From the dApp footer, **Templates & Guides → Set up a Web3 commerce store**. Two-column editor: customise on the left, preview on the right.

Configurable:

- **Store name / Title / Description** — browser-tab name vs. on-page headline vs. subtext.
- **Logo** — upload to IPFS or link to an external host.
- **Theme** — header / footer / body colours, font family. (Watch contrast; check accessibility.)
- **Navigation** — header bar or sidebar.
- **Footer** — copyright, social links, on/off.
- **Curation** — list offers from other sellers, or a subset of your own (comma-separated IDs).
- **Meta-transactions** — optional. Pay your buyers' gas via Biconomy. Requires a Biconomy API key.

When you hit **Create**, the dApp pins your storefront to IPFS and gives you a `bosonprotocol.infura-ipfs.io/ipfs/Qm…` URL. To host it on a custom domain:

- Use an [ENS](https://ens.domains/) subdomain (e.g. `store.myname.eth`).
- Front it with [ETH Limo](https://eth.limo/) for friendly access (e.g. `https://store.myname.eth.limo`).
- Or point a DNS subdomain at the IPFS gateway.

## Token gating

A token-gated product is only purchasable by buyers who hold a specified token. Currently gating is enforced on Polygon.

- **ERC-20**: gate by minimum token balance.
- **ERC-721**: gate by collection balance (any token in the contract) *or* by a specific token ID.
- **ERC-1155**: gate by a specific token ID (always required).

All gates also take an **Unlocks per wallet** count — how many times a holder can use the gate.

When a buyer browses, gated products show a lock icon over the image. On the product detail page, the gate requirements are listed; without the token they can't commit (enforced on-chain).

For the code-side equivalent: [Recipes → Token-gated launch](/recipes/token-gated).

## Fees

- **Protocol fee** — 0.5 % on successful exchanges. **No protocol fee** for offers priced in $BOSON.
- **Dispute resolution** — free for the canonical DR at launch. Other DRs may charge.
- **Gas** — Polygon transaction fees; subsidised by the dApp's meta-tx setup for sellers.

See [Concepts → Funds, escrow & payouts](/concepts/funds) for the full money-flow model.

## When to graduate to the SDK

- You need automation (auto-list, auto-fulfil).
- You want a fully custom storefront UI.
- You're handling enough volume that the manual steps don't scale.

Switch to [Tooling → Core SDK](/tooling/core-sdk) and [Quickstart → Build a marketplace](/quickstart/marketplace).

---

# Handle redemption / deliver

URL: https://www.bosonprotocol.io/docs/build/sellers/handle-redemption

> The fulfillment handoff — listening for VoucherRedeemed and triggering your delivery system.

# Handle redemption / deliver

After a buyer commits, they redeem the voucher when they're ready to receive the goods. This emits `VoucherRedeemed` on-chain and transitions the exchange from `COMMITTED` to `REDEEMED`. _This event_ is what you wire to your fulfillment system.

For the conceptual model, see [Fulfillment channels](/concepts/fulfillment) and [Eventing & indexing](/concepts/eventing).

## Listen for the event

:::code-group

```ts twoslash [Direct RPC]
// @noErrors
import { ethers } from "ethers"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"

const diamond = new ethers.Contract(DIAMOND_ADDRESS, exchangeAbi, provider)

diamond.on("VoucherRedeemed", async (offerId, exchangeId, executedBy, event) => {
  if (await alreadyDelivered(exchangeId)) return
  await deliver(exchangeId)
  await markDelivered(exchangeId)
})
```

```ts twoslash [Subgraph poll]
// @noErrors
const exchanges = await sdk.getExchanges({
  where: { state: "REDEEMED", seller: sellerId },
})

for (const exchange of exchanges) {
  if (await alreadyDelivered(exchange.id)) continue
  await deliver(exchange.id)
  await markDelivered(exchange.id)
}
```

```ts twoslash [Webhook server]
// @noErrors
// See /recipes/webhook-server for a full reference implementation.
import express from "express"
const app = express()

app.post("/webhook/redeemed", express.json(), async (req, res) => {
  const { exchangeId, txHash, logIndex } = req.body
  if (await processed(txHash, logIndex)) return res.status(200).end()
  await deliver(exchangeId)
  await mark(txHash, logIndex)
  res.status(200).end()
})
```
:::

## After delivery: complete the exchange

Once delivered, you (or anyone) can complete the exchange after the dispute window closes. This releases the seller's earnings into the treasury.

:::code-group

```ts twoslash [SDK]
// @noErrors
await (await sdk.completeExchange(exchangeId)).wait()
// or batch:
await (await sdk.completeExchangeBatch([eId1, eId2, eId3])).wait()
```

```ts twoslash [MCP]
// @noErrors
const { unsignedTx } = await mcp.completeExchange({
  configId: "production-137-0",
  signerAddress: wallet.address,
  exchangeId,
})
```
:::

## Common patterns

### Pattern: Synchronous delivery
For digital goods that can be delivered instantly, use `atomic commit-and-redeem`. The buyer commits and redeems in one transaction, and your server returns the goods in the HTTP response. See [Buyers → Atomic commit-and-redeem](/build/buyers/atomic-commit-redeem) and [Quickstart → x402 server](/quickstart/x402-server).

### Pattern: Asynchronous delivery (physical goods)
Listen to `VoucherRedeemed`, kick off your shipping flow, mark `delivered = true` keyed by `exchangeId`. Schedule `completeExchange` to run after the dispute window closes.

### Pattern: Buyer initiates fulfillment via webhook
At commit time, your widget/SDK captures a delivery address or contact. Post it to your backend keyed on `exchangeId`. On redemption, you have all the info you need to deliver.

## Common gotchas

- **Make delivery idempotent.** Reorgs and re-fired webhooks happen. Key on `exchangeId` or `(txHash, logIndex)`.
- **Subgraph polling can miss redemptions** during indexer downtime. Prefer RPC events for low-latency triggers; use the subgraph for catch-up.
- **Don't auto-complete inside the dispute window.** You can call `completeExchange`, but doing so before the window closes is a no-op and wastes gas.

## Next

- [Buyers → Redeem a voucher](/build/buyers/redeem).
- [Marketplace operators → Webhooks & events](/build/marketplace/webhooks).
- [Recipes → Webhook server for state changes](/recipes/webhook-server).

---

# Manage funds

URL: https://www.bosonprotocol.io/docs/build/sellers/manage-funds

> Deposit, withdraw, and read the seller treasury balance.

# Manage funds

A seller's funds live on-chain in a treasury slot, keyed by `sellerId`. Earnings from completed exchanges land here automatically. Deposits and withdrawals are explicit calls.

For the conceptual model, see [Funds, escrow & payouts](/concepts/funds).

:::code-group

```ts twoslash [SDK]
// @noErrors
// Read balance — getFunds takes a subgraph query-variables object.
const funds = await sdk.getFunds({ fundsFilter: { accountId: sellerId } })
// → [{ availableAmount, token: { address, decimals, symbol, name } }, …]

// Deposit (used for offers with sellerDeposit > 0, or to pre-fund a treasury)
await (await sdk.depositFunds(sellerId, tokenAddress, amount)).wait()

// Withdraw
await (await sdk.withdrawFunds(sellerId, [tokenAddress], [amount])).wait()
```

```ts twoslash [MCP]
// @noErrors
const { funds } = await mcp.getFunds({
  configId: "production-137-0",
  accountId: sellerId,
})

const { unsignedTx } = await mcp.depositFunds({
  configId: "production-137-0",
  signerAddress: wallet.address,
  accountId: sellerId,
  tokenAddress,
  amount,
})
// sign + send

const { unsignedTx: wTx } = await mcp.withdrawFunds({
  configId: "production-137-0",
  signerAddress: wallet.address,
  accountId: sellerId,
  tokenAddresses: [tokenAddress],
  amounts: [amount],
})
```
:::

## Voiding an offer

Sellers can void an offer at any time before it expires. Voiding stops new commits but doesn't affect existing exchanges.

:::code-group

```ts twoslash [SDK]
// @noErrors
await (await sdk.voidOffer(offerId)).wait()
```

```ts twoslash [MCP]
// @noErrors
const { unsignedTx } = await mcp.voidOffer({
  configId: "production-137-0",
  signerAddress: wallet.address,
  offerId,
})
```
:::

For non-listed (private / EIP-712) offers, use `void_non_listed_offer` or `void_non_listed_offer_batch` — see [Reference → MCP tools](/reference/mcp-tools).

## Common gotchas

- **Withdrawals are not gas-free.** Plan to withdraw less frequently than you complete exchanges to amortize gas.
- **Per-token withdrawals.** Each `withdrawFunds` call takes a list of token addresses + amounts. Batch them.
- **`getFunds` returns _available_ amounts only.** Funds locked in active escrow (a `COMMITTED` exchange) are not included.

## Next

- [Handle redemption / deliver](./handle-redemption).
- [Reference → Core SDK → Funds mixin](/reference/core-sdk/funds).

---

# Multi-collection

URL: https://www.bosonprotocol.io/docs/build/sellers/multi-collection

> Run multiple voucher (rNFT) collections under one seller account — one per brand, theme, or product line.

# Multi-collection

By default a seller has exactly one voucher (rNFT) contract — every offer they publish mints into that one ERC-721. Marketplaces and AMMs treat everything in the same contract as one collection, which conflates brands, themes, and product lines.

Multi-collection lets a seller create _additional_ collections, each its own ERC-721 contract instance. Every offer picks which collection it belongs to via a `collectionIndex` field. This is purely an organising layer — there's still one seller, one set of approved royalty recipients, one treasury — but external observers see distinct collections.

## When to use

- **Distinct brands under one entity.** Sell limited drops and everyday goods without mixing them on OpenSea.
- **Season releases.** Each season as its own collection makes browsing and floor-tracking sensible.
- **Marketplaces with collection-level royalty enforcement.** A separate collection gets its own ERC-2981 royalty profile, contract URI, and OpenSea collection page. Pairs well with [per-offer royalties](./royalties).

## When _not_ to use

- A single brand with many products — one collection is fine.
- You actually want separate sellers (different keys, different treasuries) → just create another seller.

## Mechanics

Collections are minimal Beacon proxies pointing at the same voucher implementation. Creating one is cheap (a clone deploy, no upgradeable proxy machinery to manage). The seller has one shared mapping `sellerId → cloneAddress[]` and every offer carries a `collectionIndex` into that array.

Index `0` is always the seller's original collection — created automatically when the seller is created. New collections are indices 1, 2, 3, ….

## Create a collection

:::code-group

```ts twoslash [SDK]
// @noErrors
// Assistant-only. Creates a new clone with its own contract URI.
await (await sdk.createNewCollection({
  collectionId: "spring-2026",         // free-form tag; used to derive collectionSalt by default
  contractUri: "ipfs://Qm…",            // OpenSea-style collection metadata JSON
  // Optional: pass an explicit collectionSalt and/or sellerId
  // collectionSalt: ethers.utils.formatBytes32String("spring-2026"),
  // sellerId: sellerId,
})).wait()

// Discover collections later (subgraph query)
const collections = await sdk.getOfferCollections({
  offerCollectionsFilter: { seller: sellerId },
})
```

```solidity [Solidity]
interface IBosonAccountHandler {
    function createNewCollection(
        string calldata _externalId,
        string calldata _contractURI
    ) external;
}
```
:::

The collection's address is deterministic via CREATE2 + `collectionSalt`, so you can compute it before sending the transaction. The `CollectionCreated` event carries the resolved address.

## Publish into a specific collection

Pass `collectionIndex` on the offer:

```ts twoslash
// @noErrors
await sdk.createOffer({
  // …offer fields…
  collectionIndex: 1, // 0 = default, 1 = first additional collection, etc.
})
```

If `collectionIndex` is out of bounds for the seller, `createOffer` reverts.

## What's shared across collections

A single seller has:

- One assistant / admin / clerk / treasury.
- One protocol treasury balance per token.
- One set of approved royalty recipients.
- One reputation / dispute history.

What's per-collection:

- The ERC-721 contract address (and therefore the OpenSea collection page).
- The `contractURI` (collection-level metadata).
- The `collectionSalt` (used at clone deploy).

Royalties are now **per-offer**, so two offers in the same collection can pay different recipients. Marketplaces that treat all tokens in a contract as one collection still see one OpenSea page but the registry honours the per-offer split.

## Common gotchas

- **Index `0` is implicit.** Don't try to `createNewCollection` for it — it was created when the seller was registered.
- **Salts are unique per seller, not global.** Two sellers can use the same `collectionSalt` and get different deterministic addresses.
- **Don't conflate with multi-seller.** If you want different keys / treasuries / dispute histories, create distinct sellers — not collections.
- **OpenSea metadata.** Set `contractURI` to a JSON document at the metadata standard OpenSea expects (`name`, `description`, `image`, `external_link`). Without it the OpenSea page is blank.

## Related

- [Sellers → Royalties](./royalties) — per-offer royalty splits within a collection.
- [Sellers → Pre-minted vouchers](./pre-minted-vouchers) — both layers can pre-mint independently.
- [Reference → Core SDK → Accounts](/reference/core-sdk/accounts) — `createNewCollection`, `getOfferCollections`.

---

# Pre-minted vouchers

URL: https://www.bosonprotocol.io/docs/build/sellers/pre-minted-vouchers

> Mint vouchers before any buyer commits. Drops, OpenSea-listable inventory, primary sales on existing marketplaces.

# Pre-minted vouchers

By default, a voucher (rNFT) is minted lazily when a buyer calls `commitToOffer`. Pre-minted vouchers let the seller pre-mint vouchers up to `quantityAvailable` before any commit, so the rNFTs exist immediately — listable on OpenSea, transferable, tradable. When a marketplace buyer "buys" the pre-minted voucher, ownership transfers and the on-chain exchange is created lazily inside the ERC-721 `before-transfer` hook, which calls the protocol's `commitToPreMintedOffer`. From the buyer's point of view, they bought an NFT; from the protocol's point of view, they committed to an offer and started the redemption clock fresh.

The seller pays the buyer's price **and** their own `sellerDeposit` at pre-mint time (out of their treasury), since the buyer doesn't interact with the protocol directly. Funds for completed exchanges flow back into the treasury automatically, so capital recycles.

## Workflow

::::steps

### `createOffer`

Normal offer creation.

### `depositFunds` (seller treasury)

Cover the seller deposit + price for each premint.

### `reserveRange(offerId, length)`

Reserve token IDs in the voucher contract.

### `preMint(offerId, amount)`

Mint in batches; vouchers are now transferable as ERC-721.

### List on OpenSea / wrap in AMM (optional)

Treat the pre-minted vouchers as ordinary ERC-721 tokens — any marketplace that supports ERC-721 will list them.

### Buyer receives voucher via ERC-721 transfer

The first transfer triggers `commitToPreMintedOffer`, creating the on-chain exchange.

### Normal protocol flow continues

Redeem / dispute / complete as if the buyer had committed directly.

::::

For convenience, the [Orchestration mixin](/reference/core-sdk/orchestration) bundles offer creation, range reservation, and (optionally) pre-mint into a single transaction — for example `createPremintedOfferWithCondition`, `createSellerAndPremintedOffer`.

## Reserve a range and pre-mint

:::code-group

```ts twoslash [SDK]
// @noErrors
// 1. (assumes you've created the offer and funded the seller treasury)

// 2. Reserve a range: length must be ≤ offer.quantityAvailable.
await (await sdk.reserveRange(offerId, /* length */ 100)).wait()

// 3. Pre-mint, possibly in batches if block gas limit is tight.
await (await sdk.preMint(offerId, /* amount */ 100)).wait()

// 4. Check what's left to mint.
const remaining = await sdk.getAvailablePreMints(offerId)

// 5. (later) Burn unused pre-minted vouchers after the offer expires or is voided.
await (await sdk.burnPremintedVouchers(offerId)).wait()
```

```ts twoslash [MCP]
// @noErrors
// reserveRange / preMintVouchers / burnPremintedVouchers aren't on the hosted MCP today;
// orchestration tools like create_offer_and_commit handle the related premint flows,
// otherwise drive the voucher-contract directly via send_signed_transaction.
```

```solidity [Solidity]
interface IBosonOfferHandler {
    function reserveRange(uint256 _offerId, uint256 _length) external;
}
interface IBosonVoucher {
    function preMint(uint256 _offerId, uint256 _amount) external;
    function burnPremintedVouchers(uint256 _offerId) external;
    function getAvailablePreMints(uint256 _offerId) external view returns (uint256);
}
```
:::

## Reserve-range mechanics

- **Single reservation per offer.** You can only call `reserveRange` once per offer — pick the length up-front.
- **Range owner.** The voucher contract or the seller's assistant address. Pre-minted vouchers transfer from this owner to the buyer.
- **Token IDs are reserved on the protocol side too** — exchange IDs and token IDs stay in lockstep, even though some exchanges are created out of order as buyers commit to pre-minted vouchers.
- **Partial pre-mint is allowed.** Reserve 10 000, pre-mint 1 000 per month. Useful for drip releases.
- **`quantityAvailable` decreases** when you reserve, not when you pre-mint.

## Capital implications

You're not just minting an NFT — you're committing the seller-side funds. For each pre-minted voucher:

| Pre-mint encumbers | Source |
| --- | --- |
| `offer.price` | Seller's protocol treasury (released to buyer if seller revokes) |
| `offer.sellerDeposit` | Seller's protocol treasury (released to seller on success) |

If your treasury runs dry the pre-mint reverts. Top up via `depositFunds(sellerId, …)`. As exchanges complete and price flows back into the treasury, that capital can cover further pre-mints — you only have to front the price for the float of unredeemed vouchers.

## Burn unused pre-minted vouchers

After an offer expires (or you void it), the pre-minted vouchers in your contract are dead inventory — they can't be committed to. `burnPremintedVouchers(offerId)` removes them so they don't appear in your wallet or on marketplaces.

## When to use pre-minted vouchers

- **Limited drops** with secondary-market-listable NFTs from day one.
- **Listing on existing NFT marketplaces** (OpenSea, Blur) before any buyer commits.
- **AMM / bonding-curve sales** — deposit pre-minted vouchers into a liquidity pool.
- **Wrapped auctions** — see [Price discovery → Wrapper flow](./price-discovery#wrapper-flow).

## When _not_ to use

- High-volume, low-value offers — lazy minting is cheaper and avoids capital lock-up.
- Offers where the buyer never sees an NFT pre-redemption — no benefit.

## Related

- [Buyers → Atomic commit-and-redeem](/build/buyers/atomic-commit-redeem) — the buyer-side counterpart.
- [Price discovery](./price-discovery) — pairs naturally with pre-minted vouchers for auctions and AMM listings.
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `IBosonOfferHandler.reserveRange`, `IBosonVoucher.preMint`.

---

# Price discovery

URL: https://www.bosonprotocol.io/docs/build/sellers/price-discovery

> Plug Boson into auctions, AMMs, order books, or any external pricing mechanism via an external Price Discovery contract.

# Price discovery

A vanilla Boson offer carries a fixed `price`. Price discovery generalises this to a callable **price discovery** contract — anything from a Seaport English auction to a Sudoswap bonding curve to a custom order book. The Diamond doesn't make any market itself; it delegates to an external contract at commit time, observes the actual price paid, and encumbers the right amount in escrow.

The price discovery integration runs through a dedicated facet (`PriceDiscoveryHandlerFacet`) and a stateless helper contract (`BosonPriceDiscoveryClient`) that owns nothing but executes the external calls — keeping the Diamond out of unrestricted-call surface area.

## The three flows

Every price-discovery commit has a **side** that determines who fulfils the order:

| Side | Description | Typical use |
| --- | --- | --- |
| **Ask** | Buyer (or someone on their behalf) fulfils | AMM / bonding curve, Seaport listing |
| **Bid** | Seller fulfils after an off-chain bid | Sealed-bid auction, RFQ |
| **Wrapper** | A wrapper contract has already settled externally; the protocol just finalises | On-chain auction where the wrapper poses as the seller |

The price-discovery payload is the same struct in all three cases:

```solidity
struct PriceDiscovery {
    uint256 price;                  // buyer's expected price
    Side side;                      // Ask | Bid | Wrapper
    address priceDiscoveryContract; // e.g. Seaport
    address conduit;                // approved-to-pull contract
    bytes priceDiscoveryData;       // arbitrary calldata for the external contract
}
```

## Prerequisite: pre-mint

Price discovery only makes sense for **pre-minted offers**. The voucher must already exist as an ERC-721 (so it can be sold on external marketplaces) before discovery happens. See [Pre-minted vouchers](./pre-minted-vouchers).

::::steps

### `createOffer` with `priceType = PriceDiscovery`

Mark the offer as price-discovery-driven at creation time.

### `depositFunds` → seller pool

Fund the seller treasury so the protocol can pull the seller deposit at commit time.

### `reserveRange` + `preMint`

Reserve token IDs and pre-mint the vouchers. They now exist as ERC-721s.

### List vouchers on an external marketplace

Seaport, AMM, etc. — the vouchers are normal NFTs from the marketplace's point of view.

### Buyer or seller calls `commitToPriceDiscoveryOffer`

Pass the `PriceDiscovery` payload (`Ask | Bid | Wrapper`). The Diamond delegates to the external contract and finalises the commit.

::::

## Ask flow — buyer fulfils

Typical example: a seller drops vouchers into a Sudoswap bonding-curve pool. A buyer wants to buy at the current curve price.

::::steps

### Buyer approves Boson Diamond for the exchange token

Seller pre-approves too — the seller deposit is encumbered at commit.

### `commitToPriceDiscoveryOffer(buyer, tokenIdOrOfferId, priceDiscovery {Ask, …})`

The buyer (or someone on their behalf) calls into the Diamond.

### Diamond → BosonPriceDiscoveryClient

1. Snapshot balances.
2. Call the price-discovery contract with `priceDiscoveryData`.
3. Compute `actualPrice = tokens flowed in − unused refund`.
4. Transfer the received voucher back to the Diamond.

### Diamond finalises the exchange

Pulls the seller deposit from the seller pool, mints the exchange, and transfers the voucher to the buyer.

::::

If the actual price < the price the buyer expected, the surplus is refunded.

## Bid flow — seller fulfils

Typical example: a sealed-bid off-chain auction. The seller runs the auction, picks a winner, and finalises through the protocol.

::::steps

### Seller approves Boson Diamond for the voucher

So the Diamond can pull the voucher when the seller's bid is accepted.

### `commitToPriceDiscoveryOffer(buyer, tokenIdOrOfferId, priceDiscovery {Bid, …})`

The seller initiates the on-chain settlement after an off-chain bid.

### Diamond pulls voucher and calls the price-discovery contract

For example, Seaport's `match` to settle the bid.

### Diamond verifies `actualPrice ≥ seller's expected price`

Reverts otherwise — the whole commit fails atomically.

::::

If the auction returns less than the seller said they'd accept, the whole commit reverts.

## Wrapper flow — pre-settled

Typical example: an on-chain auction (like a wrapped Seaport listing) that *must* be the on-chain seller of the voucher. The seller transfers the voucher to a wrapper contract; the wrapper sells it via the auction; either party then calls `commitToPriceDiscoveryOffer` to "unwrap" — the wrapper transfers the true voucher to the auction winner and sends the proceeds to the Diamond.

::::steps

### Seller transfers voucher → wrapper

Receives a wrapped voucher in return.

### Wrapper lists the wrapped voucher in the auction

The wrapper now poses as the on-chain seller.

### Auction concludes

The winner holds the wrapped voucher; proceeds sit in the wrapper.

### Either party calls `commitToPriceDiscoveryOffer` with `side = Wrapper`

Diamond invokes the wrapper's `unwrap` method. The wrapper sends the true voucher to the winner and forwards the proceeds to the Diamond.

### Diamond encumbers the proceeds

The voucher is now a normal redeemable rNFT in the protocol.

::::

Wrappers are use-case-specific; the protocol doesn't ship a canonical one, just the protocol-side machinery.

## Calling from code

:::code-group

```ts twoslash [SDK]
// @noErrors
import type { PriceDiscoveryStruct } from "@bosonprotocol/common"

const pd: PriceDiscoveryStruct = {
  price: expectedPrice,
  side: 0,                  // 0 = Ask, 1 = Bid, 2 = Wrapper
  priceDiscoveryContract: SEAPORT_ADDRESS,
  conduit: SEAPORT_CONDUIT_ADDRESS,
  priceDiscoveryData: encodedSeaportFulfilmentCalldata,
}

const tx = await sdk.commitToPriceDiscoveryOffer(
  buyerAddress,
  tokenIdOrOfferId,
  pd,
  { value: pd.price }, // only for native-token offers
)
```

```solidity [Solidity]
interface IBosonPriceDiscoveryHandler {
    function commitToPriceDiscoveryOffer(
        address payable buyer,
        uint256 tokenIdOrOfferId,
        BosonTypes.PriceDiscovery calldata priceDiscovery
    ) external payable;
}
```
:::

## Building a wrapper

A wrapper contract is just an ERC-721 receiver that:

1. Accepts a real Boson voucher, mints a wrapped twin to the sender.
2. Implements an `unwrap(tokenId, recipient)` (or similar) entry point that transfers the real voucher back out and sends the proceeds to the Diamond.
3. Approves the Boson Price Discovery client to pull the unwrapped voucher.

The shape is intentionally use-case-driven; see the [`SeaportWrapper`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/contracts/protocol/clients/voucher) in the contracts repo for a reference implementation.

## Common gotchas

- **Currency mismatch.** The external contract must trade in the offer's `exchangeToken`. The Diamond reverts if the actual flow is in a different currency.
- **Negative implied price.** If post-call tracking reports the protocol _lost_ tokens (or received fewer than zero net), the commit reverts to protect the protocol's solvency.
- **Reentrancy surface.** All external calls flow through `BosonPriceDiscoveryClient` which holds no funds and is treated as adversarial by the Diamond. Don't reuse this contract for anything else; you'll break the trust boundary.
- **Conduit approval.** For Seaport flows, the seller (or the wrapper) must approve Seaport's conduit to pull the voucher — not the Diamond.

## Related

- [Sellers → Pre-minted vouchers](./pre-minted-vouchers) — required prerequisite for most discovery flows.
- [Buyers → Sequential commit](/build/buyers/sequential-commit) — secondary-market resale uses the same price-discovery machinery.
- [Reference → Contracts → Diamond facets](/reference/contracts/facets) → `PriceDiscoveryHandlerFacet`.

---

# Publish an offer

URL: https://www.bosonprotocol.io/docs/build/sellers/publish-offer

> The core seller task. Build metadata, pin to IPFS, call createOffer.

# Publish an offer

Publishing an offer has three steps: build the metadata, pin it to IPFS, and call `createOffer`.

For the metadata pipeline in detail, see [The metadata pipeline](/concepts/metadata).

:::code-group

```ts twoslash [SDK]
// @noErrors
import { ethers } from "ethers"

// Build a PRODUCT_V1 metadata object that conforms to productV1MetadataSchema.
// See Reference → Metadata schemas for the complete shape (required fields:
// schemaUrl, type, uuid, name, description, externalUrl, licenseUrl, image,
// attributes (≥ 2), product, seller, shipping, exchangePolicy).
const uuid = crypto.randomUUID()
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "PRODUCT_V1" as const,
  uuid,
  name: "Hand-thrown mug",
  description: "Stoneware, 12 oz.",
  externalUrl: `https://example.com/${uuid}`,
  licenseUrl: `https://example.com/${uuid}/license`,
  image: "https://cdn.example.com/mug.jpg",
  attributes: [
    { traitType: "Material", value: "Stoneware" },
    { traitType: "Size", value: "12 oz" },
  ],
  product: {
    uuid,
    version: 1,
    title: "Hand-thrown mug",
    description: "Stoneware, 12 oz.",
    productionInformation_brandName: "Your brand",
    details_offerCategory: "PHYSICAL",
    visuals_images: [{ url: "https://cdn.example.com/mug.jpg", tag: "product" }],
  },
  seller: { defaultVersion: 1, name: "Your brand", contactLinks: [{ tag: "email", url: "mailto:hi@example.com" }] },
  shipping: { returnPeriod: "14" },
  exchangePolicy: { uuid: crypto.randomUUID(), version: 1, label: "fairExchangePolicy", template: "ipfs://Qm-template", sellerContactMethod: "email", disputeResolverContactMethod: "email" },
}

const metadataUri = await sdk.storeMetadata(metadata)

const tx = await sdk.createOffer({
  price: "1000000",                                      // 1 USDC
  sellerDeposit: "0",
  buyerCancelPenalty: "0",
  quantityAvailable: "10",
  exchangeToken: USDC_ADDRESS,
  metadataUri,
  metadataHash: metadataUri.replace(/^ipfs:\/\//, ""),  // the IPFS CID is the hash
  validFromDateInMS: Date.now(),
  validUntilDateInMS: Date.now() + 30 * 24 * 60 * 60 * 1000,
  voucherRedeemableFromDateInMS: Date.now(),
  voucherRedeemableUntilDateInMS: 0,
  voucherValidDurationInMS: 30 * 24 * 60 * 60 * 1000,
  disputePeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
  resolutionPeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
  collectionIndex: "0",
  disputeResolverId: "5",                                // your chain's DR; look up via getDisputeResolvers
  agentId: "0",
  feeLimit: ethers.constants.MaxUint256.toString(),     // accept any fee
})
await tx.wait()
```

```ts twoslash [MCP]
// @noErrors
// 1. Build & pin metadata
const { metadataUri, metadataHash } = await mcp.storeProductV1Metadata({
  configId: "production-137-0",
  uuid: crypto.randomUUID(),
  productV1: { title: "Hand-thrown mug", /* … */ },
})

// 2. Create offer (returns unsigned tx)
const { unsignedTx } = await mcp.createOffer({
  configId: "production-137-0",
  signerAddress: wallet.address,
  offer: {
    price: "1000000",
    sellerDeposit: "0",
    buyerCancelPenalty: "0",
    quantityAvailable: "10",
    exchangeToken: USDC_ADDRESS,
    metadataUri,
    metadataHash,
    // dates…
  },
  disputeResolverId: "5",
  agentId: "0",
  feeLimit: "0",
})

// 3. Sign and broadcast
const signed = await wallet.signTransaction(unsignedTx)
await mcp.sendSignedTransaction({ chainId: 137, signedTx: signed })
```

```solidity [Solidity]
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "@bosonprotocol/boson-protocol-contracts/contracts/BosonTypes.sol";

interface IBosonOfferHandler {
    function createOffer(
        BosonTypes.Offer calldata _offer,
        BosonTypes.OfferDates calldata _dates,
        BosonTypes.OfferDurations calldata _durations,
        uint256 _disputeResolverId,
        uint256 _agentId,
        uint256 _feeLimit
    ) external;
}
```
:::

## What this does

- Writes the offer to the Diamond (`OfferHandlerFacet.createOffer`).
- Emits `OfferCreated(offerId, sellerId, offerStruct, dispoeResolverId, agentId, /* … */)`.
- Does **not** mint vouchers yet. Vouchers are minted lazily as buyers commit — unless you opt in to [pre-minted vouchers](./pre-minted-vouchers).

## Date fields are milliseconds

All `*InMS` fields are milliseconds since Unix epoch. The SDK converts them to seconds when writing on-chain.

| Field | Meaning |
| --- | --- |
| `validFromDateInMS` | Buyers can commit starting here |
| `validUntilDateInMS` | Buyers can commit until here |
| `voucherRedeemableFromDateInMS` | Vouchers redeemable starting here |
| `voucherRedeemableUntilDateInMS` | `0` = use `voucherValidDurationInMS` |
| `voucherValidDurationInMS` | If `Until` is `0`, vouchers expire this many ms after commit |
| `disputePeriodDurationInMS` | How long after redemption the buyer can raise a dispute |
| `resolutionPeriodDurationInMS` | How long both parties have to mutually resolve a dispute before escalation |

## Atomic create + commit (orchestration)

To create an offer and commit a buyer in the same transaction (e.g. a buyer-initiated drop), use the [Orchestration mixin](/reference/core-sdk/orchestration) or the MCP `create_offer_and_commit` tool. See [Atomic commit-and-redeem](/build/buyers/atomic-commit-redeem) for the full flow.

## Common gotchas

- **`feeLimit` is the maximum fee you'll accept, in token base units.** Pass `MaxUint256` to accept any protocol fee, or a concrete max value to bail if the protocol bumps fees out from under you. **Do not pass `0` — that means "max fee = 0" and reverts with `TotalFeeExceedsLimit`.**
- **`disputeResolverId` must be registered and willing to handle your offer's `exchangeToken`.** Look up active DRs and their supported tokens via `sdk.getDisputeResolvers` or the subgraph before hard-coding an id. Each chain × env has a different DR id space.
- **`agentId = 0`** means "no protocol agent". Set it only if you have a registered agent.
- **The offer is immutable.** No update; only [void](./manage-funds#voiding-an-offer) and re-create.
- **`metadataHash` is the IPFS CID** (without the `ipfs://` prefix), not a separate keccak hash.

## Next

- [Buyers → Commit to an offer](/build/buyers/commit).
- [Variants & bundles](./bundles-variants).
- [Reference → Core SDK → Offers mixin](/reference/core-sdk/offers).

---

# Royalties

URL: https://www.bosonprotocol.io/docs/build/sellers/royalties

> Per-offer royalty configuration with multiple recipients. ERC-2981 + Royalty Registry compatible.

# Royalties

Boson moves royalty handling from the voucher contract into the Diamond. This unlocks:

- **Per-offer royalty splits** — different offers in the same voucher collection can pay different recipients at different percentages.
- **Multiple recipients per offer** — split a single sale across many parties without an off-chain splitter.
- **Royalty Registry compatibility** — works with [royaltyregistry.xyz](https://royaltyregistry.xyz/) so marketplaces that consult the registry honour the full recipient list.
- **Sequential-commit royalties** — secondary-market resales through the protocol pay royalties at finalisation time using the recipients in force at each sale (see [Sequential commit](/build/buyers/sequential-commit)).

The voucher contract still exposes ERC-2981 `royaltyInfo(tokenId, salePrice)` for marketplaces that only support a single recipient; it returns the sum of all bps and the first recipient on the list. Marketplaces that consult the Royalty Registry get the full multi-recipient breakdown.

> **bps:** _basis points_. 100 bps = 1 %. The protocol stores percentages in bps so they can be expressed without floating-point.

## Two-step model

1. **Admin pre-approves recipients on the seller**, optionally setting a per-recipient minimum royalty %.
2. **Assistant picks a subset of approved recipients per offer**, with bps that meet or exceed the admin's minimums.

The seller's treasury is always the **default recipient** (zero-address placeholder) and cannot be removed. If you later update the treasury via `updateSeller`, every offer that uses the default automatically picks up the new address — no per-offer update needed.

## Configure recipients on the seller

:::code-group

```ts twoslash [SDK]
// @noErrors
// Admin-only. Recipients can later be referenced by address from any offer.
await (await sdk.addRoyaltyRecipients(sellerId, [
  { wallet: brandA, minRoyaltyPercentage: 250,  externalId: "brand-a" }, // 2.5% minimum
  { wallet: brandB, minRoyaltyPercentage: 500,  externalId: "brand-b" }, // 5%   minimum
  { wallet: charityC, minRoyaltyPercentage: 100, externalId: "charity-c" }, // 1%  minimum
])).wait()

// Later: update or remove
await (await sdk.updateRoyaltyRecipients(sellerId, [1], [{ wallet: brandA2, minRoyaltyPercentage: 300, externalId: "brand-a-v2" }])).wait()
await (await sdk.removeRoyaltyRecipients(sellerId, [2])).wait() // remove charityC
```

```solidity [Solidity]
interface IBosonAccountHandler {
    function addRoyaltyRecipients(uint256 sellerId, BosonTypes.RoyaltyRecipient[] calldata recipients) external;
    function updateRoyaltyRecipients(uint256 sellerId, uint256[] calldata ids, BosonTypes.RoyaltyRecipient[] calldata recipients) external;
    function removeRoyaltyRecipients(uint256 sellerId, uint256[] calldata ids) external;
}
```
:::

## Set the per-offer split at creation

Offers now carry a `royaltyInfo` field. The default recipient (treasury) is `address(0)`.

```ts twoslash
// @noErrors
await sdk.createOffer({
  // …offer fields…
  royaltyInfo: {
    recipients: [
      "0x0000000000000000000000000000000000000000", // = seller treasury (default)
      brandA,
      charityC,
    ],
    bps: [200, 300, 100], // 2% to treasury, 3% to brandA, 1% to charityC → 6% total
  },
})
```

Constraints enforced by the Diamond:

- Every non-default recipient must be on the seller's approved list.
- Each `bps[i]` must be ≥ the admin-set minimum for that recipient.
- The sum of `bps` must be ≤ the protocol's `maxRoyaltyPercentage`.

## Update royalties on an existing offer

```ts twoslash
// @noErrors
await sdk.updateOfferRoyaltyRecipients(offerId, {
  recipients: [ZeroAddress, brandA],
  bps: [300, 400],
})
// Or batch
await sdk.updateOfferRoyaltyRecipientsBatch([offerId1, offerId2], { /* same shape */ })
```

This only affects **future** secondary-market sales of vouchers from that offer; commits already paid out keep their old terms.

## Reading royalty info

```ts twoslash
// @noErrors
// Full multi-recipient breakdown — call the Diamond's ERC-2981 entry point and the
// Royalty Registry. There is no `sdk.getRoyalties` / `sdk.getEIP2981Royalties`
// at the current SDK version; either build the call yourself or read from the
// subgraph.
import IBosonOfferHandler from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
const diamond = new ethers.Contract(diamondAddress, IBosonOfferHandler, provider)
const { recipients, bps } = await diamond.getRoyalties(tokenId)

// ERC-2981 reduction (single recipient, summed bps) — call the voucher contract
// (not the Diamond), e.g. via the seller's collection address:
const voucher = new ethers.Contract(voucherCollectionAddress, ["function royaltyInfo(uint256,uint256) view returns (address,uint256)"], provider)
const [receiver, royaltyAmount] = await voucher.royaltyInfo(tokenId, salePrice)
```

The Boson voucher contract exposes `royaltyInfo(tokenId, salePrice)` — the standard ERC-2981 entry point — and the Diamond carries the per-offer multi-recipient breakdown.

## Royalty Registry setup

If your offers ever have **multiple recipients**, point the registry at the Boson protocol so it returns the full breakdown:

1. Find the [Royalty Registry](https://royaltyregistry.xyz/) address on your chain.
2. Call `setRoyaltyLookupAddress(yourVoucherCollectionAddress, bosonDiamondAddress)`.

Marketplaces that honour the registry then enumerate every recipient on each secondary sale. Marketplaces that only respect ERC-2981 still pay the first recipient.

If you'd rather split one ERC-2981 royalty across many wallets, use a splitter contract (e.g. [0xSplits](https://www.0xsplits.xyz/)) as the first recipient with the full bps, and leave the others at 0 bps — they'll only be paid by registry-aware marketplaces. 

## Common gotchas

- **Zero-address = treasury.** If you put a real address in for the default split, you'll have to update every offer when the seller's treasury changes.
- **Minimum bps is per-recipient.** The minimum doesn't apply to the treasury (default) recipient.
- **No retroactive royalty changes on completed exchanges.** Royalties paid out on an exchange use the recipients that were in force at each sale event.
- **Royalty caps are protocol-level.** `maxRoyaltyPercentage` is set by `ConfigHandlerFacet`; check `protocol.getMaxRoyaltyPercentage()` before designing splits.

## Related

- [Sellers → Multi-collection](./multi-collection) — multiple voucher collections per seller, each with its own royalty profile.
- [Buyers → Sequential commit](/build/buyers/sequential-commit) — pays royalties on protocol-mediated resales.
- [Build → Royalty recipients](/build/royalty-recipients) — what the receiving side cares about.
- [Reference → Core SDK → Accounts](/reference/core-sdk/accounts) — `addRoyaltyRecipients` and friends.

---

# Sell via WooCommerce

URL: https://www.bosonprotocol.io/docs/build/sellers/woocommerce

> Install the Boson for WooCommerce plugin and add tokenized-commitment / escrow flows to your existing WordPress store.

# Sell via WooCommerce

The **Boson for WooCommerce** plugin lets a WordPress / WooCommerce store sell physical products as NFTs. Your existing storefront stays as-is; the plugin adds a redemption page where buyers redeem their rNFTs (and raise disputes), and it syncs Boson orders with your normal WooCommerce order management.

You don't need to do any blockchain transactions or pay gas — the plugin's role is to manage rNFT redemptions, disputes, and delivery info; product listing happens on the Boson dApp.

## How it works

```
1. Create a seller account + offers on the Boson dApp     (see Sellers / Sell via the Boson dApp)
2. Install the plugin & connect your Boson seller account
3. Design and customise your redemption page
4. Manage orders & fulfilment like any other WooCommerce product
```

## Requirements

- **Store** running PHP ≥ 7.3, WordPress ≥ 6.0, WooCommerce ≥ 7.4.
- The [GMP PHP Extension](https://www.php.net/manual/en/book.gmp.php) (your host may already have it).
- An [SSL certificate](https://woo.com/document/ssl-and-https/).
- A Web3 client your buyers can connect with — MetaMask or WalletConnect.

## Install

1. Find **Boson for WooCommerce** on the [WooCommerce Marketplace](https://woo.com/products/) and download the `.zip`.
2. In WordPress admin: **Plugins → Add New → Upload Plugin**, select the `.zip`, click **Install Now**.
3. **Activate** the plugin.

Updating works the same way — WordPress will ask to replace the existing version.

## Connect your seller account

1. **WooCommerce → Boson for WooCommerce.**
2. **Connect Account** (if you already have a Boson seller profile) or **Create Account** (jumps to the dApp).
3. Pick a Web3 client and connect your wallet.
4. Confirm the connected wallet address. The plugin checks on-chain that this address has a Boson seller account.
5. Click **Proceed** and sign the message in your wallet. This message signs the **origin URL** of your WooCommerce site — the Redemption Widget will only render on that domain, protecting buyers from impersonation.

Once your wallet is identified as a registered Boson seller, the plugin is ready.

If you later change the seller's wallet on the Boson side, log out of WooCommerce and log back in to re-connect. Existing product/exchange links survive.

## Build a redemption page

The plugin offers two ways to embed the Redemption Widget on a page:

**Blocks (Gutenberg-native):**
- **Boson Button Widget** — a button you can style; opens the redemption flow in a modal.
- **Boson Widget** — embeds the widget directly on the page.

**Shortcodes** (fallback for themes that don't support blocks):

```php
[boson_button text="Redeem"]
```

```php
[boson_widget]
```

If you click **Create Redemption Page** the plugin creates a basic page with the widget for you. Customise it further from the WordPress page editor; it appears under **Pages** in the WordPress admin.

## Shipping method

Choose a single shipping method that the plugin will attach to every Boson order. Whatever cost is registered against that shipping method, the plugin **forces it to 0** on Boson orders (since shipping is handled out-of-band by you and the buyer). Third-party shipping integrations can read the registered method off each order.

## Data synchronisation

After connection, the plugin syncs offers, redemptions, and disputes between Boson Protocol and WooCommerce.

- Auto-sync runs every **30 minutes**.
- Manual sync is available on demand from the plugin admin.

If a buyer redeems an rNFT *outside* WooCommerce (e.g. directly on the Boson dApp), the order appears in WooCommerce with a warning. Manage that order via the dApp — delivery info and any buyer-seller messaging happened there.

## Limitations

- **One Boson seller per WordPress site** — use multi-site if you need separate Boson identities.
- **No on-chain transactions from the plugin** — listings are still created on the Boson dApp; the plugin handles fulfilment-side ops.
- **Variations map to separate Boson offers** under a shared `productUuid`.

## Where to go next

- [Tooling → WooCommerce plugin](/tooling/woocommerce) — overview and decision criteria.
- [Recipes → Sell via WooCommerce](/recipes/woocommerce) — quick install reference.
- [Build → Sellers → Sell via the Boson dApp](./dapp) — the dApp side of listing.

---

# Build for AI agents

URL: https://www.bosonprotocol.io/docs/agents

> Patterns and pitfalls specific to autonomous agents — wallets, signing, idempotency, channels.

# Build for AI agents

If you're building an autonomous buyer or seller agent — one that operates without a human in the loop — this section is for you. It covers the concerns that only matter when there's no UI: idempotency, retry, signing, wallet management, channels.

For the _task-level_ docs (how to commit, how to publish an offer), use [Build → Sellers](/build/sellers) and [Build → Buyers](/build/buyers). The MCP tab on each task page shows the exact tool calls. This section is the layer _above_ that.

## When to read each page

| If you want to… | Read |
| --- | --- |
| Decide between hosted vs self-hosted MCP | [Hosted vs self-hosted MCP](./agents/mcp-deployment) |
| Decide between GOAT, BosonMCPClient, raw MCP | [Three integration paths](./agents/integration-paths) |
| Manage keys for agents in production | [Wallet patterns for agents](./agents/wallets) |
| Understand exactly what the agent signs | [The 3-step signing pattern](./agents/signing) |
| Make your agent survive crashes & retries | [Idempotency & retry](./agents/idempotency) |
| Persist agent state across runs | [Memory & state](./agents/memory) |
| Buy/sell over XMTP, Telegram, Email, webhook | [Channels](./agents/channels) |
| Register your agent in the dACP registry | [Agent registry](./agents/registry) |
| Sell premium / fractionalized assets | [High-value asset module](./agents/fermion) |

## Prerequisites

- A funded wallet on your target chain. See [Wallets & key management](/concepts/wallets).
- A working MCP integration. The fastest path is [Quickstart → Buy with an AI agent](/quickstart/ai-agent-buyer).
- Read [Protocol concepts → Signing & meta-transactions](/concepts/signing) — the canonical reference for everything in this section.

## The agent loop

Almost every Boson agent does this:

```
1. observe       — query offers / exchanges / subgraph
2. decide        — pick what to do (LLM in the loop, or hard-coded policy)
3. prepare       — call an MCP tool that returns an unsigned tx
4. sign          — sign with your wallet
5. broadcast     — send via send_signed_transaction or your RPC
6. wait          — for tx confirmation AND for the subgraph to index
7. verify        — re-read state to confirm the change took
8. checkpoint    — persist what you just did (idempotency key)
```

The pages in this section are about steps 4–8. Steps 1–3 are domain-specific.

---

# Channels (XMTP · Telegram · Email)

URL: https://www.bosonprotocol.io/docs/agents/channels

> Communicate with users (or other agents) outside of the on-chain transaction.

# Channels (XMTP · Telegram · Email)

On-chain transactions tell you _what happened_. They don't tell the buyer _where their thing is_, and they don't let the seller _ask the buyer a question_. For that, you need an off-chain channel.

Four channels Boson agents commonly use:

## XMTP

[XMTP](https://xmtp.org) is decentralized messaging tied to Ethereum addresses. If buyer and seller both have wallets, they have XMTP identities — no signup, no usernames.

- **Use for**: agent-to-agent commerce, delivery notifications, dispute conversations.
- **MCP tools**: `xmtp_send`, `xmtp_poll` in `WalletMCP`.

## Telegram

Telegram bots reach humans where they already are. Pair a Telegram bot with a Boson agent for human-in-the-loop seller workflows or buyer notifications.

Reference: [agent-builder/src/examples/telegram/](https://github.com/bosonprotocol/agent-builder/tree/main/src/examples/telegram).

## Email

For digital deliveries (codes, links, instructions), email is still the standard. Use any transactional email service (Resend, SendGrid, AWS SES).

Reference: [agent-builder/src/examples/email/](https://github.com/bosonprotocol/agent-builder/tree/main/src/examples/email).

## Webhooks

When the buyer is itself a server (an agent acting for a human, or an automation), receive delivery info at commit time, then POST the delivery back when ready.

See [Fulfillment channels](/concepts/fulfillment) and [Recipes → Webhook server](/recipes/webhook-server).

## Picking

| If the counterparty is… | Use |
| --- | --- |
| A human in a chat app | Telegram |
| A human at an email address | Email |
| An AI agent with a wallet | XMTP |
| A server | Webhook |

## Common gotchas

- **XMTP identities require an init message.** A buyer with no prior XMTP traffic must opt-in before you can DM them.
- **Telegram bots have per-user rate limits.** Don't blast notifications.
- **Email gets filtered as spam.** Use a reputable provider; SPF/DKIM/DMARC.

## Next

- [Fulfillment channels](/concepts/fulfillment).
- [Sellers → Handle redemption / deliver](/build/sellers/handle-redemption).

---

# High-value asset module (Fermion)

URL: https://www.bosonprotocol.io/docs/agents/fermion

> A separate MCP server for premium / fractionalized assets — adds verifier and custodian roles.

# High-value asset module (Fermion)

The Fermion module extends Boson for premium and fractionalized assets — watches, art, real estate, etc. It adds two roles not present in the base protocol:

- **Verifier** — authenticates the asset before listing.
- **Custodian** — physically holds the asset until redemption.

The module ships as a **separate MCP server** with its own tool set, alongside the main Boson MCP.

:::info
Stub. Full content TBD — including: Fermion MCP URL, tool catalogue, the verifier / custodian workflow, integration with the base Boson exchange flow, and what an agent needs to know to buy or sell a high-value asset.
:::

## When to use Fermion

- The asset value justifies the additional verification overhead.
- The asset is physical and requires storage.
- Fractional ownership is desired (multiple buyers per asset).

## Next

- Reference page TBD when Fermion MCP API stabilizes.

---

# Idempotency & retry

URL: https://www.bosonprotocol.io/docs/agents/idempotency

> How to make an autonomous agent survive crashes, partial failures, and reorgs without double-spending.

# Idempotency & retry

An agent that retries `commit_to_offer` after an RPC timeout might commit twice. An agent that doesn't retry might never recover. Get this wrong and your customers get charged twice — or not at all.

## Rule 1: every state-changing call has an idempotency key

Before calling, generate a deterministic key:

```ts
const key = `commit:${offerId}:${buyerAddress}:${intendedExchangeIdx}`
// or for ops without a natural key:
const key = randomUUID()
```

Persist it before the call. After the call (or on retry), check whether it succeeded by:

1. Looking up the key in your own state store.
2. **Or** re-reading on-chain state (e.g. `get_exchanges` for the buyer + offer pair).

Don't fire the call until you've checked both.

## Rule 2: when in doubt, re-read state

If a tool call fails or times out, you _don't know_ whether the tx landed. Always re-read before retrying:

```ts twoslash
// @noErrors
async function commitWithIdempotency(offerId, buyer) {
  const before = await mcp.getExchanges({ where: { buyer, offer: offerId } })
  const initialCount = before.length

  try {
    await commitFlow(offerId, buyer)
  } catch (err) {
    // Don't know if it succeeded — re-read.
    await mcp.waitForIndexing({ blockNumber: latestBlock })
    const after = await mcp.getExchanges({ where: { buyer, offer: offerId } })
    if (after.length > initialCount) {
      // It did succeed. Don't retry.
      return after[after.length - 1]
    }
    throw err
  }
}
```

## Rule 3: classify your errors

| Error class | Action |
| --- | --- |
| Network timeout (didn't reach server) | Safe to retry — call hasn't happened |
| RPC accepted but no receipt | **Don't retry** — re-read state first |
| Tx reverted with known reason (e.g. `OfferVoided`) | Don't retry — it's a permanent failure |
| Tx reverted with `InvalidNonce` | Re-fetch nonce, retry |
| Subgraph returned stale data | Wait for indexing, then retry the _read_, not the write |

## Rule 4: exponential backoff with jitter

```ts
const delays = [1000, 2000, 4000, 8000, 16000].map(d => d + Math.random() * 1000)
for (const d of delays) {
  try { return await tryOnce() }
  catch (e) { if (!isRetriable(e)) throw e; await sleep(d) }
}
throw new Error("exhausted retries")
```

## Rule 5: persist before retrying

If your process dies between "tx broadcast" and "tx confirmed", you need to recover. Persist intermediate state:

::::steps

### `preparing`

MCP returns an unsigned tx.

### `signed`

Wallet signs.

### `broadcast`

RPC accepts; receipt pending.

### `confirmed`

Receipt received.

### `indexed`

Subgraph caught up.

### `done`

Final state.

::::

On restart, look up the last persisted state for each in-flight key and resume.

## Common gotchas

- **The subgraph lag is a footgun.** Right after a successful commit, `getExchanges` may return empty for 1–3 blocks. Don't treat "empty" as "didn't happen" without waiting.
- **`InvalidNonce` errors don't mean failure of the original tx.** They mean the local nonce is stale. Re-fetch and re-sign.
- **Idempotency keys must be unique per intended outcome, not per attempt.** Two retries of the same intent share a key. Different intents (e.g. commits to different offers) get different keys.

## Next

- [Memory & state](./memory).
- [Concepts → Eventing & indexing](/concepts/eventing).
- [Troubleshooting → Subgraph indexing lag](/troubleshooting/indexing-lag).

---

# Three integration paths

URL: https://www.bosonprotocol.io/docs/agents/integration-paths

> GOAT SDK plugin · BosonMCPClient · raw MCP HTTP. Which to pick.

# Three integration paths

Three ways to drive Boson from an agent. Pick by control vs. convenience.

## Decision tree

```mermaid
flowchart TD
    Q1{Use Vercel AI SDK,<br/>LangChain, or Anthropic SDK?}
    Q1 -->|Yes| A["GOAT SDK plugin<br/><i>auto-registers tools, auto-signs via wallet</i>"]
    Q1 -->|No| Q2{Want typed TypeScript<br/>ergonomics?}
    Q2 -->|Yes| B[BosonMCPClient]
    Q2 -->|"No (non-TS stack /<br/>custom MCP client)"| C[Raw MCP over HTTP]
```

## GOAT SDK plugin

```ts twoslash
// @noErrors
import { bosonProtocolPlugin } from "@bosonprotocol/agentic-commerce"
import { getOnChainTools } from "@goat-sdk/adapter-vercel-ai"
import { viem } from "@goat-sdk/wallet-viem"

const tools = await getOnChainTools({
  wallet: viem(walletClient),
  plugins: [
    bosonProtocolPlugin({
      url: "https://mcp-staging.bosonprotocol.io/mcp",
    }),
  ],
})
// tools is now a dict of tool definitions, ready to register with the model
```

**Pros**: fewest moving parts. Plugin handles MCP transport + signing + broadcasting through your viem wallet.

**Cons**: opinionated. If you need custom signing (HSM, multisig, session keys), use one of the other paths.

## BosonMCPClient (typed TS)

```ts twoslash
// @noErrors
import { BosonMCPClient } from "@bosonprotocol/agentic-commerce/boson"

const mcp = new BosonMCPClient()
await mcp.connectToServer(MCP_URL)

const { unsignedTx } = await mcp.createOffer({ /* … */ })
const signed = await wallet.signTransaction(unsignedTx)
await mcp.sendSignedTransaction({ chainId, signedTx: signed })
```

**Pros**: full control over signing. Typed responses. Works with any wallet (HSM, MPC, smart account).

**Cons**: more code than the GOAT plugin. You manage the agent loop yourself.

## Raw MCP over HTTP

```ts twoslash
// @noErrors
const res = await fetch(MCP_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json,text/event-stream" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: { name: "commit_to_offer", arguments: { /* … */ } },
  }),
})
```

**Pros**: zero dependencies; any language. Useful for non-TS agents or for embedding inside an MCP-compliant client (Claude Desktop, Cline, Cursor).

**Cons**: no types, no schema validation, no signing helper.

## Mixing paths

Production agents often mix: GOAT for the LLM-driven path, BosonMCPClient for background tasks. They share the same MCP server.

## Next

- [Wallet patterns for agents](./wallets).
- [The 3-step signing pattern](./signing).
- [Tooling → MCP](/tooling/mcp).

---

# Hosted vs self-hosted MCP

URL: https://www.bosonprotocol.io/docs/agents/mcp-deployment

> Where the MCP server should run — Boson's hosted endpoints, your own deploy, or stdio.

# Hosted vs self-hosted MCP

Boson runs hosted MCP servers on Cloud Run. You can also run your own — `npx @bosonprotocol/agentic-commerce boson-mcp-server` works as either an HTTP server or stdio.

## Hosted (default)

| Env | URL |
| --- | --- |
| Staging | `https://mcp-staging.bosonprotocol.io/mcp` |
| Production | `https://mcp.bosonprotocol.io/mcp` |

Use the hosted endpoints for:
- Quickstarts and prototypes.
- Production agents where latency and uptime requirements aren't extreme.
- Anyone who doesn't want to run infrastructure.

## Self-hosted HTTP

```bash
npx @bosonprotocol/agentic-commerce boson-mcp-server --port 8080 --mode http
```

Use self-hosting when:
- You want predictable latency (e.g. co-locate with your agent).
- You need custom auth / rate-limit policies in front of the MCP.
- You want to fork the server to add custom tools.

## Self-hosted stdio (local agents)

For Claude Desktop, Cline, Cursor, etc., add to the MCP client config:

```json
{
  "mcpServers": {
    "boson": {
      "command": "npx",
      "args": ["@bosonprotocol/agentic-commerce", "boson-mcp-server", "--mode", "stdio"]
    }
  }
}
```

Stdio is process-local; no network. Best for desktop / IDE integrations.

## Picking ConfigId server-side vs per-call

The MCP server doesn't bind to a single `configId`. Every state-changing tool takes `configId` as a parameter. One MCP instance can handle staging + production traffic simultaneously.

## Common gotchas

- **Cold starts on Cloud Run.** First request after idle can take a few seconds. Keep the agent warm if your latency budget is tight.
- **Versioning.** The hosted server tracks the `main` branch of `agentic-commerce`. Self-host if you need version-pin guarantees.
- **Rate limits.** Hosted endpoints have generous but non-infinite rate limits. Self-host if you're doing >100 req/s sustained.

## Next

- [Three integration paths](./integration-paths).
- [Tooling → MCP](/tooling/mcp).

---

# Memory & state

URL: https://www.bosonprotocol.io/docs/agents/memory

> Persisting an agent's state across runs — exchanges in flight, delivery info, idempotency keys.

# Memory & state

An autonomous agent restarts. When it does, it needs to know what it was in the middle of. The minimum it must persist:

- **Idempotency keys** for in-flight tool calls. See [Idempotency & retry](./idempotency).
- **In-progress exchanges** — `exchangeId`s the agent has committed to but not yet redeemed (or not yet delivered).
- **Buyer / seller IDs** that the agent has registered.
- **Delivery info** the buyer provided at commit time (email, XMTP address, postback URL).

## Storage options

| Option | Use when |
| --- | --- |
| Local SQLite / Postgres | Single-instance agents |
| Redis / DynamoDB | Multi-instance / horizontally scaled agents |
| Per-agent storage MCP | Agents that should be relocatable across hosts |

## Per-agent storage MCPs

`agentic-commerce` ships **side MCPs** with per-agent storage (BuyerDataMCP, SellerDataMCP, WalletMCP). They expose tools like:

- `store_personal_data` / `get_personal_data` — KYC info, delivery address.
- `store_exchange_id` — track in-flight exchanges.
- `store_received_payload` — persist what was delivered.
- `xmtp_send` / `xmtp_poll` — XMTP messaging for agent-to-agent comms.
- `sign_transaction` / `sign_typed_data` — bridged wallet signing.

These keep state alongside the agent without your code holding it. Useful for agent-OS deployments (Claude Code with the Boson plugin, for example).

## Shape your state around exchange IDs

`exchangeId` is the unit of state in Boson. Index everything by it:

```sql
CREATE TABLE agent_state (
  exchange_id    TEXT PRIMARY KEY,
  config_id      TEXT NOT NULL,
  buyer_address  TEXT NOT NULL,
  seller_id      TEXT NOT NULL,
  state          TEXT NOT NULL,                      -- mirror on-chain state
  delivery_info  JSONB,
  idempotency_key TEXT,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

Reconciliation on restart: query `get_exchanges` for your buyer/seller, diff against the table, advance.

## Common gotchas

- **Don't trust the agent's own memory.** On-chain is the source of truth. Cache, don't store.
- **PII (delivery addresses, emails)** lives off-chain. Encrypt at rest; tie to `exchangeId` only.
- **Multi-tenant agents** (one agent process serving many users) need a tenant key in every row.

## Next

- [Idempotency & retry](./idempotency).
- [Channels](./channels).

---

# Agent registry

URL: https://www.bosonprotocol.io/docs/agents/registry

> Register your AI agent in the dACP agent index so it's discoverable to other agents.

# Agent registry

Boson maintains a registry of public AI agents that transact on the protocol. Registering makes your agent discoverable for agent-to-agent commerce, lets other agents query your capabilities, and is a prereq for some dACP ecosystem programs.

```ts twoslash
// @noErrors
// register_agent is server-local (no configId / signerAddress in the args).
// Fields are flat on the request body — there's no agentMetadata wrapper.
// See Reference → MCP tools → register_agent for the full schema.
await mcp.registerAgent({
  name: "MyBuyerBot",
  description: "Buys GPUs under $X.",
  entities: [
    { signerAddress: wallet.address, role: "buyer", signature: "0x…" },
  ],
})

const { agents } = await mcp.getRegisteredAgents({})
```

The registry is partly on-chain (the canonical wallet → agent-id mapping) and partly off-chain (the rich metadata).

:::info
Stub. Full content TBD — including: the metadata schema for an agent, how the GitHub-PR portion of registration works, and the discoverability semantics (who sees you, in what context).
:::

## Distinct from "protocol agent"

> The **protocol agent** ([Roles](/concepts/roles#protocol-agent)) is a fee-earning entity attached to an offer. The **AI agent registry** here is for discoverability. They're separate concepts that happen to share the word.

## Next

- [Roles](/concepts/roles).

---

# The 3-step signing pattern

URL: https://www.bosonprotocol.io/docs/agents/signing

> How every MCP state-changing tool works — return unsigned, sign locally, broadcast.

# The 3-step signing pattern

State-changing MCP tools never sign for you. They return an _unsigned_ transaction; your code signs and broadcasts. This pattern keeps private keys out of the MCP server.

For the canonical signing reference (typed-data shapes, meta-tx variants), see [Concepts → Signing & meta-transactions](/concepts/signing). This page is the agent-specific operational view.

## The three steps

```
1. Prepare    — MCP tool returns { to, data, value, gasLimit, chainId }
2. Sign       — your wallet signs the raw tx
3. Broadcast  — send via send_signed_transaction (or your own RPC)
```

```ts twoslash
// @noErrors
// 1. Prepare
const { unsignedTx } = await mcp.commitToOffer({
  configId: "production-137-0",
  signerAddress: wallet.address,
  buyer: wallet.address,
  offerId,
})

// 2. Sign
const signed = await wallet.signTransaction(unsignedTx)

// 3. Broadcast
const { txHash } = await mcp.sendSignedTransaction({
  chainId: 137,
  signedTx: signed,
})

// (optional 4) Wait for indexing before reading
await mcp.waitForIndexing({ configId: "production-137-0", blockNumber: receipt.blockNumber })
```

## Meta-transaction variant

If you want a relayer to pay gas instead of the agent:

```ts twoslash
// @noErrors
// 1. Sign the inner meta-tx envelope
const { signedMetaTx } = await mcp.signMetaTransaction({
  configId,
  functionName: "commitToOffer",
  functionArgs: { buyer, offerId },
  userAddress: wallet.address,
})

// 2. Submit through the relayer
await mcp.sendMetaTransaction(signedMetaTx)
```

Variants:
- `send_meta_transaction` — Boson-generic, via Biconomy.
- `send_native_meta_transaction` — direct on-chain EIP-712 (no relayer).
- `send_forwarded_meta_transaction` — token-auth meta-tx (single sig covers approve + call).

Pick by your gas-economics and the buyer's UX. See [Concepts → Signing](/concepts/signing).

## Per-tool signing requirements

| Tool category | Returns unsigned? | Signing required? |
| --- | --- | --- |
| `get_*` (reads) | n/a | No |
| `create_seller`, `update_seller`, `create_buyer` | Yes | Yes |
| `create_offer`, `void_offer`, … | Yes | Yes |
| `commit_to_offer`, `redeem_voucher`, `cancel_voucher`, … | Yes | Yes |
| `raise_dispute`, `resolve_dispute`, … | Yes | Yes |
| `deposit_funds`, `withdraw_funds` | Yes | Yes |
| `sign_full_offer` | Returns a signed `FullOffer` (server signs the typed-data structure) | No, but you must trust the server |
| `validate_metadata`, `render_contractual_agreement` | n/a | No |

## Common gotchas

- **`chainId` mismatch.** The unsigned tx specifies a chain. Sign with a wallet whose nonce / chain matches. Otherwise the broadcast reverts.
- **Gas limit too tight.** The MCP returns an estimated `gasLimit`; bump 20–30 % if you've seen recent reverts on full estimates.
- **Don't reuse nonces.** If two MCP `commitToOffer` calls happen in parallel without nonce coordination, one fails. Serialize or assign nonces yourself.

## Next

- [Idempotency & retry](./idempotency).
- [Concepts → Signing & meta-transactions](/concepts/signing).
- [Troubleshooting → Signature mismatches](/troubleshooting/signatures).

---

# Wallet patterns for agents

URL: https://www.bosonprotocol.io/docs/agents/wallets

> How autonomous agents should hold and use private keys — server EOA, MPC, smart accounts, session keys.

# Wallet patterns for agents

Agent wallets have different operational requirements than human wallets. There's no human to click MetaMask; the agent must sign autonomously, often hundreds of times a day.

For the general wallet discussion, see [Concepts → Wallets & key management](/concepts/wallets). This page is agent-specific.

## Pick the right pattern

| Pattern | Use when | Caveats |
| --- | --- | --- |
| **Server EOA in a managed signer** (KMS, Vault, Fireblocks, Privy, Turnkey) | Default for backend agents | Limit blast radius — separate wallet per agent role |
| **Session key** delegated from a Safe / 4337 account | Agents with bounded authority (max spend, max ops/day) | Requires smart-account wallet for the principal |
| **MPC-controlled key** | Multi-party operational control | Higher latency per signature |
| **Local EOA in env var** | **Demo / dev only** | Never in production |

## Server EOA pattern

```mermaid
flowchart TD
    Agent["Agent process<br/>(container)"] -->|sign request| KMS["KMS / Vault<br/><i>never exposes the key;<br/>signs and returns the signature</i>"]
```

The agent process never holds the raw key. It calls a signing API ("please sign this typed-data / this tx"). The SDK accepts a `signer` object — wire your KMS client into it.

## Session keys

If your agent runs untrusted code (an LLM with broad tool access), bound its authority:

1. Master wallet: a [Safe](https://safe.global) or ERC-4337 smart account. Owners are humans (or another agent).
2. Master authorizes a session key with rules: max value per tx, allowed function selectors, expiry.
3. Agent uses the session key for day-to-day Boson calls.
4. Master can revoke any time.

The Diamond's `MetaTransactionsHandlerFacet` accepts EIP-1271 signatures, so smart-account signing works out of the box.

## Funding & gas

```mermaid
flowchart TD
    Treasury["Treasury smart account<br/><i>top-up source (multisig, paymaster)</i>"] -->|"refill when balance &lt; threshold"| Agent["Agent EOA"]
```

Alerts at 0.5× / 0.2× / 0.1× expected daily burn. Don't let an agent go dark from running out of gas.

## Nonce management

If your agent fires transactions in tight loops:

- **Sequential**: easiest. Block on receipt of tx N before sending tx N+1.
- **Parallel**: track nonce yourself; bump after each `sendTransaction`. Handle out-of-order receipts.

For very high throughput, use meta-tx + a forwarder/facilitator — the relayer manages nonces for you.

## Common footguns

- **Reused keys across staging / production.** Always separate. A staging compromise must not affect production.
- **Logging full transaction objects.** They contain signatures. Logs leak.
- **Race conditions on `approve`.** Two parallel approves of the same allowance fight; the second may fail. Serialize approvals per token.

## Next

- [The 3-step signing pattern](./signing).
- [Idempotency & retry](./idempotency).
- [Concepts → Going to production](/concepts/production).

---

# Build with x402

URL: https://www.bosonprotocol.io/docs/x402

> Boson's HTTP-402 escrow stack — pay for an HTTP resource and have funds held in escrow until delivery.

# Build with x402

`x402b` extends the [x402](https://x402.org) standard with non-custodial escrow on the Boson Diamond. A buyer requests a resource, gets a `402 Payment Required` with a Boson escrow option, signs a meta-transaction, and a facilitator settles it on-chain.

:::warning
**Pre-release.** The `x402b` packages are pre-1.0 and the API surface will change between minor versions. Pin exact versions and watch the changelog.
:::

## Pages

1. [HTTP-402 + escrow concept](./x402/concept) — the model and why it exists.
2. [Buyer side (x402-client)](./x402/buyer) — making paid requests from a client.
3. [Seller side (x402-server)](./x402/seller) — protecting an HTTP resource.
4. [Facilitator (x402-facilitator)](./x402/facilitator) — running the relayer.
5. [Fulfillment channels](./x402/fulfillment) — delivering the goods after payment.
6. [Token-auth strategies](./x402/token-auth) — ERC-3009, EIP-2612, Permit2, plain approve.
7. [State-machine integration](./x402/state-machine) — advancing the exchange in `nextActions`.

## Quickstart

If you want to skip the reading and try it: [Quickstart → Accept x402 escrow payments](/quickstart/x402-server).

---

# Buyer side (x402-client)

URL: https://www.bosonprotocol.io/docs/x402/buyer

> Making paid HTTP requests from your code with x402-client and x402-client-fetch.

# Buyer side (x402-client)

A buyer's code (an agent, a CLI, a server) needs to:

1. Issue a normal HTTP request.
2. Handle a `402 Payment Required` response by signing a Boson escrow payment.
3. Re-issue the request with an `X-PAYMENT` header.

The `x402-client` package handles steps 2 and 3 transparently.

## Fetch adapter

The simplest integration is `x402-client-fetch`, which wraps `fetch`:

```ts twoslash
// @noErrors
import { createX402bClientFetch } from "@bosonprotocol/x402-client-fetch"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!)
const fetchWithPayment = createX402bClientFetch({
  signer: wallet,
  // Optional: pick token-auth + fulfillment preferences
  preferredTokenAuth: ["ERC3009", "Permit2", "Permit"],
})

const res = await fetchWithPayment("https://api.example.com/premium-thing")
console.log(await res.json())
```

When the upstream returns 402, the wrapper signs and retries automatically.

## Lower-level API

If you're not using `fetch`, use the core `x402-client`:

```ts twoslash
// @noErrors
import { createX402bClient } from "@bosonprotocol/x402-client"

const client = createX402bClient({ signer: wallet })

const challenge = parseChallenge(rawResponse)  // your HTTP lib's job
const payment = await client.buildPayment(challenge)
// payment is the value for the X-PAYMENT header
```

## Preferences

| Preference | What it controls |
| --- | --- |
| `preferredTokenAuth` | Order in which to try ERC-3009 / Permit / Permit2 / approve |
| `preferredFulfillment` | Order in which to pick inline / email / XMTP / webhook / IPFS |
| `maxValue` | Reject challenges asking for more than this |
| `allowAtomicRedeem` | Whether to accept atomic commit-and-redeem flows |

## Common gotchas

- **Token-auth mismatch.** If the seller doesn't advertise any of your preferred strategies, the client throws. Have a fallback.
- **Network mismatch.** The 402 specifies a chain; your wallet must be on it.
- **Repeated 402s.** If the seller's facilitator is down, you'll get 402 forever. Cap retries.

## Next

- [Token-auth strategies](./token-auth).
- [Recipes → x402 buyer paying for a digital asset](/recipes/x402-buyer).

---

# HTTP-402 + escrow concept

URL: https://www.bosonprotocol.io/docs/x402/concept

> The protocol-level model — why combining x402 with Boson escrow gives you non-custodial pay-per-request commerce.

# HTTP-402 + escrow concept

[x402](https://x402.org) is an open spec for in-band HTTP-402 payments: an HTTP server can respond `402 Payment Required` with payment options, and a client can re-request with payment proof in an `X-PAYMENT` header. The server validates and serves.

x402 is payment-method-agnostic. `x402b` is the Boson-flavored scheme that uses Boson escrow as the payment method.

## Why escrow?

Plain x402 says "send funds and you get the resource". Escrow x402 says "lock funds; the resource must be delivered before they release; either party can dispute".

This gets you:

- **Non-custodial.** No platform holds money.
- **Dispute resolution.** If the delivery is broken, the buyer can raise a dispute. Boson's DR resolves.
- **Re-fundable.** A failed delivery refunds automatically.
- **Composable with other Boson features** — vouchers (rNFTs), royalties, agent fees.

## The flow

```mermaid
sequenceDiagram
    autonumber
    participant Client
    participant Seller as Seller server
    participant Facilitator as Facilitator<br/>(x402-facilitator)
    participant Diamond as Boson Diamond

    Client->>Seller: GET /thing
    Seller-->>Client: 402 Payment Required<br/>(advertises Boson escrow option)
    Note over Client: signs meta-tx<br/>+ token-auth
    Client->>Seller: GET /thing + X-PAYMENT
    Seller->>Facilitator: forward signed payment
    Facilitator->>Diamond: submit commit
    Note over Diamond: on-chain commit
    Diamond-->>Diamond: (optional) atomic redeem
    Diamond-->>Facilitator: receipt
    Facilitator-->>Seller: settled
    Seller-->>Client: 200 OK + asset<br/>(or fulfillment-channel pointer)
```

## Two flows

| Flow | Description | Best for |
| --- | --- | --- |
| **Deferred** | Commit now; redeem later (buyer or server triggers) | Physical goods, time-bounded redemption |
| **Atomic** | Commit + redeem in one tx | Digital goods, agent-to-agent commerce |

## Where it differs from plain x402

| Plain x402 | x402b (Boson escrow) |
| --- | --- |
| Pay direct | Pay to escrow |
| Trust the seller | Trust the protocol |
| No native dispute | Built-in dispute resolution |
| Generic | Boson-specific (offers, exchanges) |

## Next

- [Buyer side](./buyer).
- [Seller side](./seller).
- [Facilitator](./facilitator).

---

# Facilitator (x402-facilitator)

URL: https://www.bosonprotocol.io/docs/x402/facilitator

> The relayer that submits signed meta-transactions to the Diamond on behalf of buyers.

# Facilitator (x402-facilitator)

The facilitator is the relayer that takes a signed x402 payment payload, validates it, and submits the on-chain transaction. It pays gas on behalf of the buyer.

You can either run your own facilitator or use a hosted one.

## Run your own

```ts twoslash
// @noErrors
import express from "express"
import { createX402bFacilitatorExpress } from "@bosonprotocol/x402-facilitator-express"
import { ethers } from "ethers"

const relayerWallet = new ethers.Wallet(process.env.RELAYER_PRIVATE_KEY!)
const app = express()

app.use("/", createX402bFacilitatorExpress({
  signer: relayerWallet,
  supportedChains: [137, 8453],
}))

app.listen(8080)
```

## The three endpoints

A facilitator exposes:

- `POST /verify` — check whether a signed payment is valid (without submitting).
- `POST /settle` — submit it on-chain.
- `POST /perform-action?action=<action>` — settle and advance the exchange (e.g. atomic redeem).

## Library shape

If you want to embed facilitator logic into an existing service, use `x402-facilitator` directly:

```ts twoslash
// @noErrors
import { verify, settle, performAction } from "@bosonprotocol/x402-facilitator"

const result = await settle(paymentPayload, { signer: relayerWallet })
// result: { ok: true, exchangeId, txHash } | { ok: false, code, reason }
```

## Gas economics

The facilitator pays gas. To stay solvent:

- Charge a relayer fee per request (off-band, e.g. token markup on the price).
- Cap allowed values to keep gas burn bounded.
- Monitor relayer wallet balance; alert on low balance.

## Common gotchas

- **Don't trust the buyer's signature blindly.** Always `verify` before `settle`.
- **Race conditions.** Two facilitators racing for the same payment causes one tx to revert. Use idempotency keys.
- **Nonce stampedes.** Under high concurrency, your relayer wallet's nonce becomes a hotspot. Use a nonce manager.

## Next

- [State-machine integration](./state-machine).
- [Reference → x402b packages → x402-facilitator](/reference/x402/x402-facilitator).

---

# Fulfillment channels (x402)

URL: https://www.bosonprotocol.io/docs/x402/fulfillment

> How the seller delivers the asset after on-chain settlement.

# Fulfillment channels (x402)

After the facilitator confirms on-chain settlement, the seller's server delivers the asset. The x402 challenge advertised which channels are available; the buyer picked one.

For the canonical reference (channels and trade-offs), see [Concepts → Fulfillment channels](/concepts/fulfillment).

## Built-in channels

| Channel | Delivery |
| --- | --- |
| **Inline** | Seller's HTTP response carries the asset directly |
| **Email** | Server sends an email to a buyer-supplied address |
| **XMTP** | Server posts to the buyer's XMTP identity |
| **Webhook** | Server POSTs to a buyer-supplied URL |
| **IPFS pointer** | Server returns an IPFS CID; buyer fetches separately |

## Implementing a channel

```ts twoslash
// @noErrors
import type { FulfillmentChannel } from "@bosonprotocol/x402-fulfillment"

const inline: FulfillmentChannel = {
  id: "inline",
  async fulfill({ asset, request, response }) {
    response.json(asset)
  },
}
```

Register the channel with the server:

```ts twoslash
// @noErrors
import { ChannelRegistry } from "@bosonprotocol/x402-fulfillment"

const registry = new ChannelRegistry([inline, email, xmtp])
const x402 = createX402bServerExpress({ /* …, */ channelRegistry: registry })
```

## Buyer-chosen, seller-bound

The buyer's client picks the channel; the seller's server must support it. Negotiation happens at the 402 step — the server advertises only channels it implements.

## Custom channels

The `FulfillmentChannel` interface is open. Add your own (Slack DM, on-chain log, in-game inventory) by implementing `fulfill()`.

## Common gotchas

- **The buyer's contact info comes in the X-PAYMENT envelope** (for email/XMTP). Validate / sanitize before using.
- **Inline channel can't deliver large assets.** Use IPFS pointer for >1 MB payloads.
- **Webhook handlers must be authenticated** — HMAC-sign the payload.

## Next

- [Concepts → Fulfillment channels](/concepts/fulfillment).
- [Recipes → x402 server email-fulfillment](/recipes/x402-email).

---

# Seller side (x402-server)

URL: https://www.bosonprotocol.io/docs/x402/seller

> Protecting an HTTP resource behind a Boson escrow payment requirement.

# Seller side (x402-server)

`x402-server` is a framework-agnostic SDK for building x402b-enabled HTTP services. `x402-server-express` is the Express adapter.

## Express

```ts twoslash
// @noErrors
import express from "express"
import { createX402bServerExpress } from "@bosonprotocol/x402-server-express"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.SELLER_PRIVATE_KEY!)
const app = express()

const x402 = createX402bServerExpress({
  network: "polygon",
  chainId: 137,
  escrow: {
    configId: "production-137-0",
    sellerId: "12",
    productUuid: "ec00f1a5-2c96-4d22-9d80-2a7c12345678",
  },
  signer: wallet,
  facilitator: { url: "https://facilitator.bosonprotocol.io" },
})

app.get("/api/inference", x402.middleware(), async (req, res) => {
  // req.x402 is populated: { exchangeId, buyer, paidAt }
  const result = await runInference(req.query.prompt)
  res.json(result)
})

app.listen(3000)
```

## What the middleware does

1. Look for `X-PAYMENT` header.
2. If missing → return 402 with the escrow option built from your config.
3. If present → validate (signature, amount, expiry, token).
4. POST to the facilitator → wait for on-chain settlement.
5. Populate `req.x402` with exchange info.
6. Call your handler.

## Configuring the escrow option

Every 402 response advertises one or more `accepts` payment options. `escrow` is the one this stack adds.

```ts
escrow: {
  configId,
  sellerId,
  productUuid,
  // Optional: dynamic price
  amount: "1000000",                  // 1 USDC, in token base units
  asset: "0x...",                     // USDC address on the chain
  // Optional: fulfillment options to advertise
  fulfillment: { channels: ["inline", "email"] },
}
```

For dynamic pricing, compute these at request time inside your handler.

## FullOffer signing hook

When the offer isn't pre-published on-chain (non-listed), the server must sign a `FullOffer` for the buyer to commit against. The factory takes a `signFullOffer` hook:

```ts
signFullOffer: async (offerDraft) => {
  // … your custom logic, then …
  return await sdk.signFullOffer(offerDraft)
}
```

## Common gotchas

- **CORS.** The 402 response must include CORS headers if your client is browser-based.
- **Idempotency.** A retried request with the same `X-PAYMENT` must not double-charge. Cache `(paymentHash) → exchangeId`.
- **Facilitator outage.** If the facilitator is down, the middleware returns 503. Have a circuit breaker.

## Next

- [Facilitator](./facilitator).
- [State-machine integration](./state-machine).
- [Recipes → x402 server email-fulfillment](/recipes/x402-email).

---

# State-machine integration

URL: https://www.bosonprotocol.io/docs/x402/state-machine

> Advancing the exchange in the same response — `x402-actions` and the `nextActions` envelope.

# State-machine integration

A plain x402b commit moves the exchange to `COMMITTED`. But many digital-goods sellers want to atomically redeem in the same request, or to advertise a follow-up action the buyer should take. `x402-actions` is the layer that exposes this.

## `nextActions` envelope

In the 402 response (and in some 200 responses), the server can include `nextActions[]` — a list of state transitions the buyer could take next, with the endpoint to call.

Example:

```json
{
  "accepts": [{ "scheme": "escrow", "...": "..." }],
  "nextActions": [
    {
      "action": "boson-redeem",
      "channel": "facilitator",
      "endpoint": "https://facilitator.bosonprotocol.io/perform-action?action=boson-redeem"
    }
  ]
}
```

## Channels and adapters

`nextActions[]` entries have a `channel` (`onchain`, `facilitator`, `server`, `mcp`). Each channel has a `ChannelAdapter` that knows how to execute the action via its endpoint.

```ts twoslash
// @noErrors
import { FacilitatorChannelAdapter } from "@bosonprotocol/x402-actions"

const adapter = new FacilitatorChannelAdapter({ endpoint: "..." })
await adapter.perform({ action: "boson-redeem", payload })
```

## Computing legal next actions

`x402-actions` ships the state tables from `x402-core`. Given the current exchange state, it returns which actions are legal — so the server doesn't advertise illegal transitions.

```ts twoslash
// @noErrors
import { computeNextActions } from "@bosonprotocol/x402-actions"

const next = computeNextActions({
  state: "COMMITTED",
  role: "buyer",
})
// → ["redeem", "cancel"]
```

## When to use atomic redeem

Atomic commit-and-redeem is the right call when:
- The asset is digital and delivered in the response.
- The buyer doesn't need a redemption window (no physical goods).
- You're optimizing for one round-trip.

For physical goods, keep commit and redeem separate; the buyer redeems when they physically receive the package.

## Common gotchas

- **`nextActions` order matters.** The client picks the first one whose `channel` it can speak.
- **Action endpoints can be stale.** Always include a fresh endpoint per response, not a static URL.

## Next

- [Reference → x402b packages → x402-actions](/reference/x402/x402-actions).
- [Buyers → Atomic commit-and-redeem](/build/buyers/atomic-commit-redeem).

---

# Token-auth strategies

URL: https://www.bosonprotocol.io/docs/x402/token-auth

> Four ways for the buyer to authorize the token transfer in a single signed envelope — ERC-3009, EIP-2612, Permit2, or plain approve.

# Token-auth strategies

A buyer paying with an ERC-20 needs to authorize the Boson Diamond (or a facilitator) to pull tokens. There are four ways to do this; x402 supports all of them. Picking the right one is a trade-off between buyer signature count and token support.

For the canonical reference, see [Concepts → Signing → Token-auth meta-tx](/concepts/signing#token-auth-meta-tx).

| Strategy | Sig count | Token support |
| --- | --- | --- |
| **ERC-3009** (receive-with-authorization) | 1 | USDC, EURC, some others |
| **EIP-2612** (Permit) | 1 | DAI, many ERCs |
| **Permit2** (Uniswap's) | 1 | Any ERC-20, via Permit2 contract |
| **Plain approve** + commit | 2 | Any ERC-20 |

## Decision tree

```mermaid
flowchart TD
    Q1{Token is USDC / EURC /<br/>similar EIP-3009 token?}
    Q1 -->|Yes| A["ERC-3009<br/><i>cleanest</i>"]
    Q1 -->|No| Q2{Token implements<br/>EIP-2612 permit?}
    Q2 -->|Yes| B[EIP-2612 Permit]
    Q2 -->|No| C["Permit2<br/><i>works for any ERC-20</i>"]
    C -.fallback.-> D["Plain approve + commit<br/><i>2 sigs</i>"]
```

## ERC-3009

The buyer signs a `ReceiveWithAuthorization` payload. The Diamond's `executeMetaTransactionWithTokenTransferAuthorization` pulls the tokens and executes the call atomically.

## EIP-2612 Permit

The buyer signs a `Permit` payload that grants the Diamond allowance with a deadline. The Diamond consumes the permit + executes the call.

## Permit2

Permit2 is a separate contract (Uniswap's). It can hold authority over any ERC-20 the user has approved Permit2 for. Then the buyer signs a Permit2 envelope per use.

The Permit2 contract address is fixed per chain. See [Networks → Contract addresses](/networks/addresses).

## Plain approve + commit

Two transactions. The buyer:
1. Calls `IERC20.approve(diamond, amount)`.
2. Calls `commitToOffer`.

Two wallet confirmations. Use only when other strategies aren't available.

## Configuring preferences

On the buyer client:

```ts
preferredTokenAuth: ["ERC3009", "Permit2", "Permit", "approve"]
```

The client picks the first one the seller advertises.

## Common gotchas

- **Permit2 requires a one-time setup**: the user must approve Permit2 itself for each token. After that, individual uses are gas-less authorizations.
- **EIP-2612 doesn't work for USDC.** USDC has its own non-standard permit. Use ERC-3009 instead.
- **The chain matters.** Permit2 is deployed at the same address on most EVMs but not all. Check.

## Next

- [Concepts → Signing & meta-transactions](/concepts/signing).
- [Troubleshooting → Approve · Permit · Permit2](/troubleshooting/approvals).

---

# Embeddable widgets — overview

URL: https://www.bosonprotocol.io/docs/widgets

> Drop-in UI for committing, redeeming, and managing funds.

# Embeddable widgets

Three drop-in widgets handle the three most common buyer-side flows. Each is a hosted React app embeddable via `<script>` + button, `<iframe>`, or [Zoid](https://github.com/krakenjs/zoid).

| Widget | Purpose |
| --- | --- |
| [Commit Widget](./widgets/commit) | Buyer accepts an offer and pays |
| [Redemption Widget](./widgets/redemption) | Buyer redeems, cancels, or disputes |
| [Finance Widget](./widgets/finance) | Seller/buyer manages on-chain funds |

For embedding, configuration, styling, and postback details:

- [Embedding methods](./widgets/embedding)
- [Configuration & ConfigIds](./widgets/configuration)
- [Styling & theming](./widgets/styling)
- [Postback URLs & deep links](./widgets/postback)

## Hosted at

`https://widgets.bosonprotocol.io/` — the canonical deployment.

## Versioning

Widgets are continuously deployed from the `widgets` repo and follow the React Kit version. Pin a SHA-stamped URL if you need version stability.

## Quickstart

[Quickstart → Embed a commit button](/quickstart/commit-button) — 5 minutes.

---

# Commit Widget

URL: https://www.bosonprotocol.io/docs/widgets/commit

> A drop-in modal that takes a buyer from "see an offer" to "committed and holding a voucher".

# Commit Widget

The Commit Widget is the most-used widget. Place a button on your page; on click, it opens a modal that:

1. Connects the buyer's wallet.
2. Shows the offer details.
3. Handles ERC-20 approval if needed.
4. Calls `commitToOffer`.
5. Confirms success and shows the new voucher (rNFT).

## Embed

```html
<script src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js" async></script>

<button
  id="boson-commit"
  data-config-id="production-137-0"
  data-seller-id="12"
  data-product-uuid="ec00f1a5-2c96-4d22-9d80-2a7c12345678">
  Buy now
</button>
```

## Key attributes

| Attribute | Required? | Notes |
| --- | --- | --- |
| `id="boson-commit"` | Yes | Marker so the widget script finds the button |
| `data-config-id` | Yes | See [Networks → ConfigIds matrix](/networks/configids) |
| `data-seller-id` | One of these | Targets all offers from one seller |
| `data-product-uuid` | One of these | Targets a specific product (incl. variants) |
| `data-bundle-uuid` | One of these | Targets a bundle |
| `data-offer-id` | One of these | Targets a single offer |
| `data-account` | No | Restrict to one buyer wallet |
| `data-look-and-feel` | No | `"modal"` (default) or `"regular"` |

Full list at [Reference → Widget URL params](/reference/widget-params).

## Variants & products

If you publish 3 variants under one `productUuid`, the widget lets the buyer pick a variant before committing. Each variant is its own offer underneath.

## Programmatic open

If you don't want a button:

```ts
window.boson.openCommit({
  configId: "production-137-0",
  sellerId: "12",
  productUuid: "...",
})
```

## Common gotchas

- **Wrong chain.** The buyer's wallet must be on the chain that matches `configId`. The widget prompts a switch.
- **Iframe ancestors.** If you embed inside another iframe, ensure the buyer's wallet provider supports nested-iframe access (some don't).
- **CSP.** Allow `widgets.bosonprotocol.io` in `script-src` and `frame-src`.

## Next

- [Embedding methods](./embedding) — iframe and Zoid alternatives.
- [Configuration & ConfigIds](./configuration).
- [Postback URLs & deep links](./postback).

---

# Configuration & ConfigIds

URL: https://www.bosonprotocol.io/docs/widgets/configuration

> Every widget needs a configId. This page explains how to pick one and what else you can configure.

# Configuration & ConfigIds

Every widget takes a `configId` that selects the deployment (env × chain × index). For the format and full list, see [Concepts → Networks & ConfigIds](/concepts/networks-and-configids).

## Picking a ConfigId

```html
<!-- Polygon mainnet -->
data-config-id="production-137-0"

<!-- Base mainnet -->
data-config-id="production-8453-0"

<!-- Base Sepolia testnet -->
data-config-id="staging-84532-0"
```

Match it to your seller / offer's chain. Cross-chain widgets don't exist — one widget instance, one chain.

## Other commonly-set attributes

| Attribute | Effect |
| --- | --- |
| `data-account` | Restrict to one wallet address |
| `data-look-and-feel` | `"modal"` (default) or `"regular"` |
| `data-modal-margin` | Margin around the modal in CSS units |
| `data-postback-url` | Server URL to receive lifecycle events |
| `data-theme-overrides` | JSON string of CSS variable overrides |

Full set: [Reference → Widget URL params](/reference/widget-params).

## Next

- [Styling & theming](./styling).
- [Postback URLs & deep links](./postback).

---

# Embedding methods

URL: https://www.bosonprotocol.io/docs/widgets/embedding

> Script + button, iframe, or Zoid — three ways to put a Boson widget on a page.

# Embedding methods

The hosted widgets ship in three flavours: a loader script that finds tagged buttons on your page, an `<iframe>` you embed directly, and a [Zoid](https://github.com/krakenjs/zoid) cross-origin component for more advanced cases.

## Script + button (recommended)

```html
<script src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js" async></script>
<button id="boson-commit" data-config-id="..." data-product-uuid="...">Buy now</button>
```

Pros: simplest. The loader handles modal lifecycle, wallet connection, and event bubbling.

## Iframe

```html
<iframe
  src="https://widgets.bosonprotocol.io/#/commit?configId=production-137-0&productUuid=..."
  width="600" height="800"
  allow="clipboard-write; web-share"
></iframe>
```

Pros: works in environments where you can't run scripts (some CMS / locked-down pages).

Cons: communication is harder (use `postMessage` for events; see [Postback URLs](./postback) instead for server-side).

## Zoid (cross-origin component)

```ts twoslash
// @noErrors
import { create } from "@krakenjs/zoid"

const Commit = create({
  tag: "boson-commit",
  url: "https://widgets.bosonprotocol.io/#/commit",
  dimensions: { width: "600px", height: "800px" },
})

Commit.render({
  configId: "production-137-0",
  productUuid: "...",
  onCommit: (exchangeId) => { /* … */ },
}, "#mount")
```

Pros: typed props, lifecycle callbacks, full DOM isolation.

Cons: more setup; one more dependency.

## When to use which

| Need | Use |
| --- | --- |
| Simplest possible | Script + button |
| No JS allowed | Iframe |
| Typed props and callbacks | Zoid |

## Next

- [Configuration & ConfigIds](./configuration).
- [Postback URLs & deep links](./postback).
- [Reference → Widget URL params](/reference/widget-params).

---

# Finance Widget

URL: https://www.bosonprotocol.io/docs/widgets/finance

> A drop-in UI for managing on-chain funds — sellers deposit and withdraw from their protocol treasury, plus per-token balance views.

# Finance Widget

The Finance Widget exposes the protocol treasury for a seller (and for buyers / dispute resolvers / agents who have funds locked up): per-token available balances, deposit, withdraw. Embed it where sellers manage their account — a dashboard, a back-office page, or a settings modal.

Under the hood it's `@bosonprotocol/react-kit`'s `<FinanceWidget />`, surfaced through the hosted build at [`widgets.bosonprotocol.io`](https://widgets.bosonprotocol.io/).

## Quickest embed: script + button

```html
<script async type="text/javascript" src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js"></script>

<button id="boson-finance"
  data-config-id="production-137-0"
  data-seller-id="12">
  Manage funds
</button>
```

The widget filters to the connected wallet by default. To force a specific seller (e.g. when the connected wallet is the assistant and you want to manage a different seller's treasury), pass `data-seller-id` together with `data-with-external-signer="true"`.

## Attributes

| Attribute | Required? | Notes |
| --- | --- | --- |
| `data-config-id` | Yes | See [Networks → ConfigIds matrix](/networks/configids). |
| `data-seller-id` | Together with `data-with-external-signer` | On-chain entity ID to manage. Without it, the widget falls back to the connected wallet's entity. |
| `data-with-external-signer` | Together with `data-seller-id` | `"true"` means you'll sign transactions externally and pass them through — useful when the seller is a smart account or held in custody. |
| `data-look-and-feel` | No | `"modal"` (default) or `"regular"`. |
| `data-theme-overrides` | No | JSON-encoded CSS variable overrides. |

## Iframe form (no JS loader)

```html
<iframe
  src="https://widgets.bosonprotocol.io/#/finance?configId=production-137-0&sellerId=12&withExternalSigner=true"
  width="100%" height="800"
  allow="clipboard-write; web-share">
</iframe>
```

Every `data-*` attribute maps 1:1 to a URL query param of the same name (camelCase, without the `data-` prefix).

## What the widget shows

For a seller account (or any account-holding entity):

- **Available balances per token** — only what's withdrawable, _not_ what's locked in active exchanges (`COMMITTED`, `REDEEMED`, `DISPUTED`).
- **Deposit** — top up the treasury per token; needed for offers with `sellerDeposit > 0`, for pre-minted offers, and for buyer-side prepayment under [buyer-initiated offers](/build/buyers/buyer-initiated).
- **Withdraw** — pull tokens out to the entity's treasury address. Batched by token.

Funds locked in active escrow are intentionally omitted — withdrawing them isn't possible until the corresponding exchanges finalise. To inspect locked funds, query the subgraph directly (see [Concepts → Funds, escrow & payouts](/concepts/funds)).

## React Kit — when you want full control

```tsx
import { FinanceWidget } from "@bosonprotocol/react-kit"

<FinanceWidget
  configId="production-137-0"
  envName="production"
  sellerId="12"
  withExternalSigner
  withReduxProvider
  withWeb3React
  withGlobalStyle
  walletConnectProjectId={WC_PROJECT_ID}
  // …
/>
```

See the [widgets repo](https://github.com/bosonprotocol/widgets) for the complete prop list.

## Common gotchas

- **Treasury vs. wallet.** Withdrawal goes to the **treasury address** configured on the entity, not the wallet that signed the withdraw. To redirect, call `updateSeller` first.
- **Per-token withdrawal.** One `withdrawFunds` call takes an array of `(tokenAddress, amount)` pairs — the widget batches the user's selection into a single transaction.
- **Native vs. ERC-20.** Native gas tokens appear as `0x0000…0000` in balances and don't need approvals. ERC-20s show the symbol resolved via the supported-tokens config.
- **Gas isn't free.** Even when the widget hides it (most flows use meta-tx where possible), some chains require the signer to hold gas. Surface that requirement to the user when balance is empty.
- **DR and agent treasuries work the same way.** Set `data-seller-id` to the DR or agent ID and the widget renders their balances; the protocol treats all entity-holders uniformly under `FundsHandlerFacet`.

## Next

- [Concepts → Funds, escrow & payouts](/concepts/funds) — the money-flow model the widget is a UI for.
- [Build → Sellers → Manage funds](/build/sellers/manage-funds) — the equivalent SDK calls.
- [Widgets → Embedding methods](./embedding).

---

# Postback URLs & deep links

URL: https://www.bosonprotocol.io/docs/widgets/postback

> Receive server-side notifications when a widget user commits or redeems.

# Postback URLs & deep links

Widget interactions are off-server by default — the buyer's browser talks to the chain. To capture events on your backend (record the order in your CRM, fire fulfillment), use a **postback URL**.

## Configure

```html
<button
  id="boson-commit"
  data-config-id="..."
  data-postback-url="https://yourserver.example.com/boson/postback">
  Buy now
</button>
```

## Payload

The widget POSTs JSON to your endpoint after each lifecycle event:

```json
{
  "event": "committed",
  "exchangeId": "456",
  "buyer": "0x...",
  "offerId": "123",
  "txHash": "0x...",
  "configId": "production-137-0",
  "timestamp": 1742345678
}
```

Events: `committed`, `redeemed`, `disputed`, `cancelled`, `revoked`.

## Authentication

The widget signs the payload with HMAC using a secret you supply at widget config:

```html
data-postback-secret="<your secret>"
```

Verify on your server using the matching secret.

## Deep links

To open the widget from a URL (e.g. a deep link in an email):

```
https://widgets.bosonprotocol.io/#/commit?configId=production-137-0&productUuid=...&account=0x...
```

The widget mounts in fullscreen mode. Useful for share / claim links.

## Common gotchas

- **Postbacks are not retried by default.** If your endpoint is down, the event is lost. Pair with a [webhook server](/build/marketplace/webhooks) that listens to on-chain events as a backstop.
- **HMAC verification is mandatory in production.** Without it, anyone can POST to your endpoint with fake events.

## Next

- [Marketplace operators → Webhooks & events](/build/marketplace/webhooks).
- [Recipes → Webhook server](/recipes/webhook-server).

---

# Redemption Widget

URL: https://www.bosonprotocol.io/docs/widgets/redemption

> A drop-in flow for buyers to redeem, cancel, or dispute their committed exchanges — script-tag, iframe, or React.

# Redemption Widget

The Redemption Widget lets a buyer act on the vouchers (rNFTs) they already hold. It shows their exchanges in the protocol, lets them redeem, cancel before redemption, raise disputes after redemption, and (for sellers) revoke or complete exchanges. The widget detects what state each exchange is in and surfaces only the actions that make sense.

Where it shines: when you sell vouchers on a different surface (your own storefront, the Boson dApp, an NFT marketplace, a metaverse, an in-game shop) but want one canonical place buyers come back to redeem. Drop the widget on your domain and your customers redeem there.

The hosted build is at [`widgets.bosonprotocol.io`](https://widgets.bosonprotocol.io/) — under the hood it's a React app over `@bosonprotocol/react-kit`'s `<RedemptionWidget />`.

## Quickest embed: script + button

```html
<script async type="text/javascript" src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js"></script>

<button id="boson-redeem" data-config-id="production-137-0">Redeem</button>
```

The loader script finds the button by its `id`, mounts the modal, and handles wallet connect. The buyer signs in with whatever EIP-1193 wallet they prefer; the widget filters to their committed exchanges automatically.

### Optional Boson-branded styling

```html
<head>
  <link rel="stylesheet" href="https://widgets.bosonprotocol.io/styles.css">
</head>
<body>
  <button id="boson-redeem" class="bosonButton" data-config-id="production-137-0">Show Redeem</button>
</body>
```

## Filtering and deep-linking

| Attribute | Effect |
| --- | --- |
| `data-config-id` (required) | Deployment to query — see [Networks → ConfigIds matrix](/networks/configids). |
| `data-account` | Restrict to a single buyer wallet (otherwise uses the connected wallet). |
| `data-exchange-id` | Open directly to one exchange — buyer skips the selection screen. |
| `data-seller-ids` (comma-list) or `data-seller-id` | Filter to exchanges from one or more sellers. |
| `data-signatures` (comma-list) | Multi-seller domain-binding signatures — see [WooCommerce → connect](/build/sellers/woocommerce#connect-your-seller-account). |
| `data-look-and-feel` | `"modal"` (default) or `"regular"` for inline rendering. |
| `data-widget-action` | Force a starting screen — `SELECT_EXCHANGE` (default), `EXCHANGE_DETAILS`, `REDEEM_FORM`, `CANCEL_FORM`, `CONFIRM_REDEEM`. |
| `data-exchange-state` | Pre-filter to `COMMITTED` / `REDEEMED` / `DISPUTED` / `COMPLETED`. |
| `data-show-redemption-overview` | `"true"` (default) shows the overview pane on entry; `"false"` jumps straight to the action. |

## Iframe form (no JS loader)

For sites that block third-party scripts:

```html
<iframe
  src="https://widgets.bosonprotocol.io/#/redeem?configId=production-137-0&exchangeId=80"
  width="100%" height="800"
  allow="clipboard-write; web-share">
</iframe>
```

Every `data-*` attribute above maps 1:1 to a URL query param of the same name (without the `data-` prefix; camelCase: `exchangeId`, `widgetAction`, `lookAndFeel`, etc.).

## Programmatic open

```ts
window.boson.openRedeem({
  configId: "production-137-0",
  exchangeId: "80",
  widgetAction: "REDEEM_FORM",
})
```

## Capturing delivery info on your server

When a buyer redeems a physical product, the widget collects the delivery info. You have three options for where it goes:

### 1. XMTP to the seller (default)

The widget posts the info as an XMTP message keyed to the seller's wallet. The seller's fulfilment system reads it from their XMTP inbox. Zero infrastructure on your end.

Enable: `data-send-delivery-info-through-xmtp="true"`.

### 2. POST to your endpoint

Your server receives the delivery info as a POST. Useful when you have an existing OMS / WMS / CRM.

```html
<button id="boson-redeem"
  data-config-id="production-137-0"
  data-post-delivery-info-url="https://yourshop.example.com/api/boson/delivery"
  data-post-delivery-info-headers='{"Authorization": "Bearer …"}'>
  Redeem
</button>
```

The widget POSTs `{ exchangeId, deliveryInfo, signature, … }`. Validate the signature server-side before processing.

### 3. postMessage to the parent window

If the widget is embedded in your dApp and you want to handle delivery info entirely in the parent page:

```html
data-target-origin="https://yourshop.example.com"
```

The widget calls `window.parent.postMessage({ exchangeId, deliveryInfo, eventTag }, targetOrigin)`. Useful for fully-custom checkout-style integrations.

## Lifecycle callbacks (backend)

Three optional server endpoints fire at the redemption lifecycle:

| Attribute | When it fires |
| --- | --- |
| `data-post-redemption-submitted-url` | Buyer's redeem transaction broadcast (not yet confirmed). |
| `data-post-redemption-confirmed-url` | Redemption transaction confirmed on-chain. |
| `data-post-delivery-info-url` | Delivery info collected (see above). |

Each has a paired `*-headers` attribute (JSON-encoded) for auth headers. Treat these as fire-and-forget — the widget doesn't retry, so handlers must be idempotent (key on `exchangeId`).

## React Kit — when you want full control

If you'd rather skip the hosted build:

```tsx
import { RedemptionWidget } from "@bosonprotocol/react-kit"

<RedemptionWidget
  configId="production-137-0"
  envName="production"
  withReduxProvider
  withWeb3React
  withGlobalStyle
  exchangeId="80"
  widgetAction="REDEEM_FORM"
  closeWidgetClick={() => { /* … */ }}
  deliveryInfoHandler={(info) => { /* … */ }}
  redemptionSubmittedHandler={(tx) => { /* … */ }}
  redemptionConfirmedHandler={(tx) => { /* … */ }}
  // … same props as the URL query params, plus a few extras …
/>
```

See the [widgets repo](https://github.com/bosonprotocol/widgets) for the full prop catalogue.

## Common gotchas

- **Wrong chain.** The buyer's wallet must be on the chain that matches `configId`. The widget prompts a switch but some wallets reject silently.
- **CSP.** Allow `widgets.bosonprotocol.io` in `script-src`, `frame-src`, and `connect-src` (the latter for postback URLs and XMTP).
- **Multi-seller storefronts** need per-seller `signatures` to prove origin-binding — otherwise the widget refuses to render to protect buyers from spoofed sellers.
- **Delivery info handlers are not retried** by the widget — your endpoint must be idempotent (dedupe on `exchangeId`). Pair with on-chain event listeners ([Build → Marketplace operators → Webhooks & events](/build/marketplace/webhooks)) as the backstop.

## Next

- [Build → Buyers → Redeem a voucher](/build/buyers/redeem) — what `redeemVoucher` actually does.
- [Build → Buyers → Raise a dispute](/build/buyers/raise-dispute).
- [Widgets → Embedding methods](./embedding).
- [Widgets → Postback URLs & deep links](./postback).

---

# Styling & theming

URL: https://www.bosonprotocol.io/docs/widgets/styling

> Override CSS variables to match your brand.

# Styling & theming

The hosted widgets use CSS custom properties so you can override colors, fonts, and spacing from outside.

## Override via data attribute

```html
<button
  id="boson-commit"
  data-config-id="..."
  data-theme-overrides='{"colors": {"primary": "#ff6f61", "background": "#0e0e10"}, "font": "Inter, sans-serif"}'>
  Buy now
</button>
```

## Override via CSS

```css
:root {
  --boson-color-primary: #ff6f61;
  --boson-color-background: #0e0e10;
  --boson-font-family: "Inter", sans-serif;
}
```

The widget reads from `:root` after mount.

## Dark mode

Pass `data-theme="dark"`, or use a media query that flips your CSS variables on `prefers-color-scheme: dark`.

## Custom CSS

For deeper customization (custom button styles, modal animations), embed via Zoid and style your wrapper. The widget's _inner_ DOM is in an iframe and not directly stylable.

## Next

- [Configuration & ConfigIds](./configuration).
- [Embedding methods](./embedding).

---

# Reference

URL: https://www.bosonprotocol.io/docs/reference

> Canonical, mostly auto-generated, one-page-per-symbol reference for every Boson surface.

# Reference

The reference is the source of truth for symbols, signatures, and schemas. Most pages here are **auto-generated** from the underlying source — zod schemas, TypeChain factories, Solidity ABIs, GraphQL queries. The pipeline that produces them lives at [`scripts/docs-gen/`](https://github.com/bosonprotocol/docs.bosonprotocol.io/tree/main/scripts/docs-gen).

Generated pages carry a banner: _"Generated from `<source>@<commit>`. Edit the source, not this page."_

## Sections

- [Core SDK](./reference/core-sdk/core-sdk) — `@bosonprotocol/core-sdk` and its mixins.
- [MCP tools](./reference/mcp-tools) — all ~56 tools, one page per tool.
- [Contracts](./reference/contracts/facets) — Diamond facets, events, errors, structs.
- [React Kit](./reference/react-kit) — components and hooks.
- [x402b packages](./reference/x402/x402-core) — the seven `x402-*` packages.
- [Metadata schemas](./reference/metadata) — `PRODUCT_V1`, `BUNDLE`, `BASE`.
- [Subgraph queries](./reference/subgraph) — GraphQL schema and common queries.
- [Widget URL params](./reference/widget-params) — every parameter accepted by hosted widgets.

## Conventions

- **TypeScript types** are rendered with [Twoslash](https://twoslash.netlify.app); hover over identifiers in code blocks for inline type info.
- **Solidity types** are rendered from NatSpec; click through to GitHub for the source.
- **Zod schemas** are rendered as inline tables with type, required/optional, default.
- **Errors** are listed per-page with code, when-thrown, and what-to-do.

## When the reference is wrong

Open an issue or PR against the source-of-truth file, not the generated page. The pipeline rebuilds on every commit.

## Searching

The site search is biased _down_ for Reference pages (so concept queries land on Concepts first). To search reference specifically, use the search input on this page or browse the sidebar.

---

# Reference — Contracts: Custom errors

URL: https://www.bosonprotocol.io/docs/reference/contracts/errors

> Every custom error a Boson Diamond call can revert with.

# Custom errors

:::info
**Generated from `boson-protocol-contracts/addresses/abis/polygon`. Edit the Solidity sources, not this page.**
:::

When a Diamond call reverts, it carries a custom-error selector. The SDK's `parseError()` decodes it; here's the full list as a lookup.

## Catalogue (181 errors)

| Error | Parameters | Defined in |
| --- | --- | --- |
| `AccessDenied` | `()` | `IBosonAccountHandler` |
| `AddressesAndCalldataLengthMismatch` | `()` | `IBosonAccountHandler` |
| `AdminOrAuthToken` | `()` | `IBosonAccountHandler` |
| `AgentAddressMustBeUnique` | `()` | `IBosonAccountHandler` |
| `AgentFeeAmountTooHigh` | `()` | `IBosonAccountHandler` |
| `AlreadyInitialized` | `()` | `IBosonAccountHandler` |
| `AmbiguousVoucherExpiry` | `()` | `IBosonAccountHandler` |
| `AmountExceedsRangeOrNothingToBurn` | `()` | `IBosonAccountHandler` |
| `ArrayLengthMismatch` | `()` | `IBosonAccountHandler` |
| `AuthTokenMustBeUnique` | `()` | `IBosonAccountHandler` |
| `BundleForTwinExists` | `()` | `IBosonAccountHandler` |
| `BundleOfferMustBeUnique` | `()` | `IBosonAccountHandler` |
| `BundleRequiresAtLeastOneTwinAndOneOffer` | `()` | `IBosonAccountHandler` |
| `BundleTwinMustBeUnique` | `()` | `IBosonAccountHandler` |
| `BuyerAddressMustBeUnique` | `()` | `IBosonAccountHandler` |
| `CannotCommit` | `()` | `IBosonAccountHandler` |
| `CannotRemoveDefaultRecipient` | `()` | `IBosonAccountHandler` |
| `ClerkDeprecated` | `()` | `IBosonAccountHandler` |
| `CloneCreationFailed` | `()` | `IBosonAccountHandler` |
| `DirectInitializationNotAllowed` | `()` | `IBosonAccountHandler` |
| `DisputeHasExpired` | `()` | `IBosonAccountHandler` |
| `DisputePeriodHasElapsed` | `()` | `IBosonAccountHandler` |
| `DisputePeriodNotElapsed` | `()` | `IBosonAccountHandler` |
| `DisputeResolverAddressMustBeUnique` | `()` | `IBosonAccountHandler` |
| `DisputeResolverFeeNotFound` | `()` | `IBosonAccountHandler` |
| `DisputeStillValid` | `()` | `IBosonAccountHandler` |
| `DRFeeMutualizerCannotProvideCoverage` | `()` | `IBosonAccountHandler` |
| `DRUnsupportedFee` | `()` | `IBosonAccountHandler` |
| `DuplicateDisputeResolverFees` | `()` | `IBosonAccountHandler` |
| `EscalationNotAllowed` | `()` | `IBosonAccountHandler` |
| `ExchangeAlreadyExists` | `()` | `IBosonAccountHandler` |
| `ExchangeForOfferExists` | `()` | `IBosonAccountHandler` |
| `ExchangeIdInReservedRange` | `()` | `IBosonAccountHandler` |
| `ExchangeIsNotInAFinalState` | `()` | `IBosonAccountHandler` |
| `ExternalCallFailed` | `()` | `IBosonAccountHandler` |
| `FeeAmountTooHigh` | `()` | `IBosonAccountHandler` |
| `FeeTableAssetNotSupported` | `()` | `IBosonAccountHandler` |
| `FunctionNotAllowlisted` | `()` | `IBosonAccountHandler` |
| `GroupHasCondition` | `()` | `IBosonAccountHandler` |
| `GroupHasNoCondition` | `()` | `IBosonAccountHandler` |
| `IncomingVoucherAlreadySet` | `()` | `IBosonAccountHandler` |
| `InexistentAllowedSellersList` | `()` | `IBosonAccountHandler` |
| `InexistentDisputeResolverFees` | `()` | `IBosonAccountHandler` |
| `InsufficientAvailableFunds` | `()` | `IBosonAccountHandler` |
| `InsufficientTwinSupplyToCoverBundleOffers` | `()` | `IBosonAccountHandler` |
| `InsufficientValueReceived` | `()` | `IBosonAccountHandler` |
| `InteractionNotAllowed` | `()` | `IBosonAccountHandler` |
| `InvalidAddress` | `()` | `IBosonAccountHandler` |
| `InvalidAgentFeePercentage` | `()` | `IBosonAccountHandler` |
| `InvalidAmount` | `()` | `IBosonAccountHandler` |
| `InvalidAmountToMint` | `()` | `IBosonAccountHandler` |
| `InvalidAuthTokenType` | `()` | `IBosonAccountHandler` |
| `InvalidBuyerOfferFields` | `()` | `IBosonAccountHandler` |
| `InvalidBuyerPercent` | `()` | `IBosonAccountHandler` |
| `InvalidCollectionIndex` | `()` | `IBosonAccountHandler` |
| `InvalidConditionParameters` | `()` | `IBosonAccountHandler` |
| `InvalidConduitAddress` | `()` | `IBosonAccountHandler` |
| `InvalidDisputePeriod` | `()` | `IBosonAccountHandler` |
| `InvalidDisputeResolver` | `()` | `IBosonAccountHandler` |
| `InvalidDisputeTimeout` | `()` | `IBosonAccountHandler` |
| `InvalidEscalationPeriod` | `()` | `IBosonAccountHandler` |
| `InvalidFeePercentage` | `()` | `IBosonAccountHandler` |
| `InvalidFunctionName` | `()` | `IBosonAccountHandler` |
| `InvalidOffer` | `()` | `IBosonAccountHandler` |
| `InvalidOfferCreator` | `()` | `IBosonAccountHandler` |
| `InvalidOfferPenalty` | `()` | `IBosonAccountHandler` |
| `InvalidOfferPeriod` | `()` | `IBosonAccountHandler` |
| `InvalidPriceDiscovery` | `()` | `IBosonAccountHandler` |
| `InvalidPriceDiscoveryPrice` | `()` | `IBosonAccountHandler` |
| `InvalidPriceType` | `()` | `IBosonAccountHandler` |
| `InvalidQuantityAvailable` | `()` | `IBosonAccountHandler` |
| `InvalidRangeLength` | `()` | `IBosonAccountHandler` |
| `InvalidRangeStart` | `()` | `IBosonAccountHandler` |
| `InvalidRedemptionPeriod` | `()` | `IBosonAccountHandler` |
| `InvalidResolutionPeriod` | `()` | `IBosonAccountHandler` |
| `InvalidRoyaltyFee` | `()` | `IBosonAccountHandler` |
| `InvalidRoyaltyInfo` | `()` | `IBosonAccountHandler` |
| `InvalidRoyaltyPercentage` | `()` | `IBosonAccountHandler` |
| `InvalidRoyaltyRecipient` | `()` | `IBosonAccountHandler` |
| `InvalidRoyaltyRecipientId` | `()` | `IBosonAccountHandler` |
| `InvalidSellerOfferFields` | `()` | `IBosonAccountHandler` |
| `InvalidSignature` | `()` | `IBosonAccountHandler` |
| `InvalidState` | `()` | `IBosonAccountHandler` |
| `InvalidSupplyAvailable` | `()` | `IBosonAccountHandler` |
| `InvalidTargeDisputeState` | `()` | `IBosonAccountHandler` |
| `InvalidTargeExchangeState` | `()` | `IBosonAccountHandler` |
| `InvalidToAddress` | `()` | `IBosonAccountHandler` |
| `InvalidTokenAddress` | `()` | `IBosonAccountHandler` |
| `InvalidTokenId` | `()` | `IBosonAccountHandler` |
| `InvalidTwinProperty` | `()` | `IBosonAccountHandler` |
| `InvalidTwinTokenRange` | `()` | `IBosonAccountHandler` |
| `MaxCommitsReached` | `()` | `IBosonAccountHandler` |
| `MustBeActive` | `()` | `IBosonAccountHandler` |
| `NativeNotAllowed` | `()` | `IBosonAccountHandler` |
| `NativeWrongAddress` | `()` | `IBosonAccountHandler` |
| `NativeWrongAmount` | `()` | `IBosonAccountHandler` |
| `NegativePriceNotAllowed` | `()` | `IBosonAccountHandler` |
| `NonAscendingOrder` | `()` | `IBosonAccountHandler` |
| `NonceUsedAlready` | `()` | `IBosonAccountHandler` |
| `NoPendingUpdateForAccount` | `()` | `IBosonAccountHandler` |
| `NoReservedRangeForOffer` | `()` | `IBosonAccountHandler` |
| `NoSilentMintAllowed` | `()` | `IBosonAccountHandler` |
| `NoSuchAgent` | `()` | `IBosonAccountHandler` |
| `NoSuchBundle` | `()` | `IBosonAccountHandler` |
| `NoSuchBuyer` | `()` | `IBosonAccountHandler` |
| `NoSuchCollection` | `()` | `IBosonAccountHandler` |
| `NoSuchDisputeResolver` | `()` | `IBosonAccountHandler` |
| `NoSuchEntity` | `()` | `IBosonAccountHandler` |
| `NoSuchExchange` | `()` | `IBosonAccountHandler` |
| `NoSuchGroup` | `()` | `IBosonAccountHandler` |
| `NoSuchOffer` | `()` | `IBosonAccountHandler` |
| `NoSuchSeller` | `()` | `IBosonAccountHandler` |
| `NoSuchTwin` | `()` | `IBosonAccountHandler` |
| `NotAdmin` | `()` | `IBosonAccountHandler` |
| `NotAdminAndAssistant` | `()` | `IBosonAccountHandler` |
| `NotAgentWallet` | `()` | `IBosonAccountHandler` |
| `NotAssistant` | `()` | `IBosonAccountHandler` |
| `NotAuthorized` | `()` | `IBosonAccountHandler` |
| `NotBuyerOrSeller` | `()` | `IBosonAccountHandler` |
| `NotBuyerWallet` | `()` | `IBosonAccountHandler` |
| `NotDisputeResolverAssistant` | `()` | `IBosonAccountHandler` |
| `NothingToWithdraw` | `()` | `IBosonAccountHandler` |
| `NothingUpdated` | `()` | `IBosonAccountHandler` |
| `NotOfferCreator` | `()` | `IBosonAccountHandler` |
| `NotPaused` | `()` | `IBosonAccountHandler` |
| `NoTransferApproved` | `()` | `IBosonAccountHandler` |
| `NotVoucherHolder` | `()` | `IBosonAccountHandler` |
| `NoUpdateApplied` | `()` | `IBosonAccountHandler` |
| `OfferExpiredOrVoided` | `()` | `IBosonAccountHandler` |
| `OfferHasBeenVoided` | `()` | `IBosonAccountHandler` |
| `OfferHasExpired` | `()` | `IBosonAccountHandler` |
| `OfferMustBeActive` | `()` | `IBosonAccountHandler` |
| `OfferMustBeUnique` | `()` | `IBosonAccountHandler` |
| `OfferNotAvailable` | `()` | `IBosonAccountHandler` |
| `OfferNotInBundle` | `()` | `IBosonAccountHandler` |
| `OfferNotInGroup` | `()` | `IBosonAccountHandler` |
| `OfferRangeAlreadyReserved` | `()` | `IBosonAccountHandler` |
| `OfferSoldOut` | `()` | `IBosonAccountHandler` |
| `OfferStillValid` | `()` | `IBosonAccountHandler` |
| `PriceDoesNotCoverPenalty` | `()` | `IBosonAccountHandler` |
| `PriceMismatch` | `()` | `IBosonAccountHandler` |
| `ProtocolInitializationFailed` | `()` | `IBosonAccountHandler` |
| `RecipientNotUnique` | `()` | `IBosonAccountHandler` |
| `ReentrancyGuard` | `()` | `IBosonAccountHandler` |
| `RegionPaused` | `(uint8 region)` | `IBosonAccountHandler` |
| `RoyaltyRecipientIdsNotSorted` | `()` | `IBosonAccountHandler` |
| `SameMutualizerAddress` | `()` | `IBosonAccountHandler` |
| `SellerAddressMustBeUnique` | `()` | `IBosonAccountHandler` |
| `SellerAlreadyApproved` | `()` | `IBosonAccountHandler` |
| `SellerNotApproved` | `()` | `IBosonAccountHandler` |
| `SellerParametersNotAllowed` | `()` | `IBosonAccountHandler` |
| `SellerSaltNotUnique` | `()` | `IBosonAccountHandler` |
| `SignatureValidationFailed` | `()` | `IBosonAccountHandler` |
| `TokenAmountMismatch` | `()` | `IBosonAccountHandler` |
| `TokenIdMandatory` | `()` | `IBosonAccountHandler` |
| `TokenIdMismatch` | `()` | `IBosonAccountHandler` |
| `TokenIdNotInConditionRange` | `()` | `IBosonAccountHandler` |
| `TokenIdNotSet` | `()` | `IBosonAccountHandler` |
| `TokenTransferFailed` | `()` | `IBosonAccountHandler` |
| `TotalFeeExceedsLimit` | `()` | `IBosonAccountHandler` |
| `TwinNotInBundle` | `()` | `IBosonAccountHandler` |
| `TwinsAlreadyExist` | `()` | `IBosonAccountHandler` |
| `TwinTransferUnsuccessful` | `()` | `IBosonAccountHandler` |
| `UnauthorizedCallerUpdate` | `()` | `IBosonAccountHandler` |
| `UnexpectedDataReturned` | `(bytes data)` | `IBosonAccountHandler` |
| `UnexpectedERC721Received` | `()` | `IBosonAccountHandler` |
| `UnsupportedMutualizer` | `()` | `IBosonAccountHandler` |
| `UnsupportedToken` | `()` | `IBosonAccountHandler` |
| `ValueZeroNotAllowed` | `()` | `IBosonAccountHandler` |
| `VersionMustBeSet` | `()` | `IBosonAccountHandler` |
| `VoucherExtensionNotValid` | `()` | `IBosonAccountHandler` |
| `VoucherHasExpired` | `()` | `IBosonAccountHandler` |
| `VoucherNotReceived` | `()` | `IBosonAccountHandler` |
| `VoucherNotRedeemable` | `()` | `IBosonAccountHandler` |
| `VoucherNotTransferred` | `()` | `IBosonAccountHandler` |
| `VoucherStillValid` | `()` | `IBosonAccountHandler` |
| `VoucherTransferNotAllowed` | `()` | `IBosonAccountHandler` |
| `WalletOwnsVouchers` | `()` | `IBosonAccountHandler` |
| `WrongCurrentVersion` | `()` | `IBosonAccountHandler` |
| `WrongDefaultRecipient` | `()` | `IBosonAccountHandler` |
| `ZeroDepositNotAllowed` | `()` | `IBosonAccountHandler` |

## How to decode

```ts twoslash
// @noErrors
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"
import disputeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonDisputeHandler.json"
import fundsAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonFundsHandler.json"
import priceAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonPriceDiscoveryHandler.json"
import { ethers } from "ethers"

const iface = new ethers.utils.Interface([...offerAbi, ...exchangeAbi, ...disputeAbi, ...fundsAbi, ...priceAbi])
try {
  iface.parseError(err.data ?? err.error?.data)
} catch { /* not a known custom error */ }
```

Or higher-level:

```ts twoslash
// @noErrors
const parsed = sdk.parseError(err)
// → { code: "OfferVoided", args: { offerId: "123" } }
```

## Source

- ABI artifacts: [`boson-protocol-contracts/addresses/abis/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/addresses/abis)
- Errors lib: [`BosonErrors.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/protocol/libs/BosonErrors.sol)

## Related

- [Troubleshooting → Reverts & error codes](/troubleshooting/reverts) — top causes and fixes.

---

# Reference — Contracts: Events

URL: https://www.bosonprotocol.io/docs/reference/contracts/events

> Every event emitted by the Boson Diamond.

# Events

:::info
**Generated from `boson-protocol-contracts/addresses/abis/polygon`. Edit the Solidity sources, not this page.**
:::

The Diamond emits all events at the same contract address (the proxy). Decode with the merged ABI from `@bosonprotocol/common`, not a single-facet ABI.

## Catalogue (85 events)

### `AccessControllerAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event AccessControllerAddressChanged(address (indexed) accessControllerAddress, address (indexed) executedBy);
```

### `AgentCreated`

_From_ `IBosonAccountHandler`

```solidity
event AgentCreated(uint256 (indexed) agentId, (uint256, uint256, address, bool) agent, address (indexed) executedBy);
```

### `AgentUpdated`

_From_ `IBosonAccountHandler`

```solidity
event AgentUpdated(uint256 (indexed) agentId, (uint256, uint256, address, bool) agent, address (indexed) executedBy);
```

### `AllowedSellersAdded`

_From_ `IBosonAccountHandler`

```solidity
event AllowedSellersAdded(uint256 (indexed) disputeResolverId, uint256[] addedSellers, address (indexed) executedBy);
```

### `AllowedSellersRemoved`

_From_ `IBosonAccountHandler`

```solidity
event AllowedSellersRemoved(uint256 (indexed) disputeResolverId, uint256[] removedSellers, address (indexed) executedBy);
```

### `AuthTokenContractChanged`

_From_ `IBosonConfigHandler`

```solidity
event AuthTokenContractChanged(uint8 (indexed) authTokenType, address (indexed) authTokenContract, address (indexed) executedBy);
```

### `BeaconProxyAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event BeaconProxyAddressChanged(address (indexed) beaconProxyAddress, address (indexed) executedBy);
```

### `BundleCreated`

_From_ `IBosonBundleHandler`

```solidity
event BundleCreated(uint256 (indexed) bundleId, uint256 (indexed) sellerId, (uint256, uint256, uint256[], uint256[]) bundle, address (indexed) executedBy);
```

### `BuyerCommitted`

_From_ `IBosonExchangeCommitHandler`

```solidity
event BuyerCommitted(uint256 (indexed) offerId, uint256 (indexed) buyerId, uint256 (indexed) exchangeId, (uint256, uint256, uint256, uint256, uint8, address) exchange, (uint256, uint256, uint256, bool) voucher, address executedBy);
```

### `BuyerCreated`

_From_ `IBosonAccountHandler`

```solidity
event BuyerCreated(uint256 (indexed) buyerId, (uint256, address, bool) buyer, address (indexed) executedBy);
```

### `BuyerEscalationFeePercentageChanged`

_From_ `IBosonConfigHandler`

```solidity
event BuyerEscalationFeePercentageChanged(uint256 buyerEscalationFeePercentage, address (indexed) executedBy);
```

### `BuyerInitiatedOfferSetSellerParams`

_From_ `IBosonExchangeCommitHandler`

```solidity
event BuyerInitiatedOfferSetSellerParams(uint256 (indexed) offerId, uint256 (indexed) sellerId, (uint256, (address[], uint256[]), address) sellerParams, address executedBy);
```

### `BuyerUpdated`

_From_ `IBosonAccountHandler`

```solidity
event BuyerUpdated(uint256 (indexed) buyerId, (uint256, address, bool) buyer, address (indexed) executedBy);
```

### `CollectionCreated`

_From_ `IBosonAccountHandler`

```solidity
event CollectionCreated(uint256 (indexed) sellerId, uint256 collectionIndex, address collectionAddress, string (indexed) externalId, address (indexed) executedBy);
```

### `ConditionalCommitAuthorized`

_From_ `IBosonExchangeCommitHandler`

```solidity
event ConditionalCommitAuthorized(uint256 (indexed) offerId, uint8 gating, address (indexed) buyerAddress, uint256 (indexed) tokenId, uint256 commitCount, uint256 maxCommits);
```

### `DisputeDecided`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeDecided(uint256 (indexed) exchangeId, uint256 _buyerPercent, address (indexed) executedBy);
```

### `DisputeEscalated`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeEscalated(uint256 (indexed) exchangeId, uint256 (indexed) disputeResolverId, address (indexed) executedBy);
```

### `DisputeExpired`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeExpired(uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `DisputeRaised`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeRaised(uint256 (indexed) exchangeId, uint256 (indexed) buyerId, uint256 (indexed) sellerId, address executedBy);
```

### `DisputeResolved`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeResolved(uint256 (indexed) exchangeId, uint256 _buyerPercent, address (indexed) executedBy);
```

### `DisputeResolverCreated`

_From_ `IBosonAccountHandler`

```solidity
event DisputeResolverCreated(uint256 (indexed) disputeResolverId, (uint256, uint256, address, address, address, address, string, bool) disputeResolver, (address, string, uint256)[] disputeResolverFees, uint256[] sellerAllowList, address (indexed) executedBy);
```

### `DisputeResolverFeesAdded`

_From_ `IBosonAccountHandler`

```solidity
event DisputeResolverFeesAdded(uint256 (indexed) disputeResolverId, (address, string, uint256)[] disputeResolverFees, address (indexed) executedBy);
```

### `DisputeResolverFeesRemoved`

_From_ `IBosonAccountHandler`

```solidity
event DisputeResolverFeesRemoved(uint256 (indexed) disputeResolverId, address[] feeTokensRemoved, address (indexed) executedBy);
```

### `DisputeResolverUpdateApplied`

_From_ `IBosonAccountHandler`

```solidity
event DisputeResolverUpdateApplied(uint256 (indexed) disputeResolverId, (uint256, uint256, address, address, address, address, string, bool) disputeResolver, (uint256, uint256, address, address, address, address, string, bool) pendingDisputeResolver, address (indexed) executedBy);
```

### `DisputeResolverUpdatePending`

_From_ `IBosonAccountHandler`

```solidity
event DisputeResolverUpdatePending(uint256 (indexed) disputeResolverId, (uint256, uint256, address, address, address, address, string, bool) pendingDisputeResolver, address (indexed) executedBy);
```

### `DisputeRetracted`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeRetracted(uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `DisputeTimeoutExtended`

_From_ `IBosonDisputeHandler`

```solidity
event DisputeTimeoutExtended(uint256 (indexed) exchangeId, uint256 newDisputeTimeout, address (indexed) executedBy);
```

### `DRFeeRequested`

_From_ `IBosonDisputeHandler`

```solidity
event DRFeeRequested(uint256 (indexed) exchangeId, address (indexed) tokenAddress, uint256 feeAmount, address (indexed) mutualizerAddress, address executedBy);
```

### `DRFeeReturned`

_From_ `IBosonDisputeHandler`

```solidity
event DRFeeReturned(uint256 (indexed) exchangeId, address (indexed) tokenAddress, uint256 returnAmount, address (indexed) mutualizerAddress, address executedBy);
```

### `DRFeeReturnFailed`

_From_ `IBosonDisputeHandler`

```solidity
event DRFeeReturnFailed(uint256 (indexed) exchangeId, address (indexed) tokenAddress, uint256 returnAmount, address (indexed) mutualizerAddress, address executedBy);
```

### `EscalatedDisputeExpired`

_From_ `IBosonDisputeHandler`

```solidity
event EscalatedDisputeExpired(uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `EscalatedDisputeRefused`

_From_ `IBosonDisputeHandler`

```solidity
event EscalatedDisputeRefused(uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `ExchangeCompleted`

_From_ `IBosonExchangeCommitHandler`

```solidity
event ExchangeCompleted(uint256 (indexed) offerId, uint256 (indexed) buyerId, uint256 (indexed) exchangeId, address executedBy);
```

### `FeeTableUpdated`

_From_ `IBosonConfigHandler`

```solidity
event FeeTableUpdated(address (indexed) token, uint256[] priceRanges, uint256[] feePercentages, address (indexed) executedBy);
```

### `FunctionsAllowlisted`

_From_ `IBosonMetaTransactionsHandler`

```solidity
event FunctionsAllowlisted(bytes32[] functionNameHashes, bool isAllowlisted, address (indexed) executedBy);
```

### `FundsDeposited`

_From_ `IBosonDisputeHandler`

```solidity
event FundsDeposited(uint256 (indexed) entityId, address (indexed) executedBy, address (indexed) tokenAddress, uint256 amount);
```

### `FundsEncumbered`

_From_ `IBosonDisputeHandler`

```solidity
event FundsEncumbered(uint256 (indexed) entityId, address (indexed) exchangeToken, uint256 amount, address (indexed) executedBy);
```

### `FundsReleased`

_From_ `IBosonDisputeHandler`

```solidity
event FundsReleased(uint256 (indexed) exchangeId, uint256 (indexed) entityId, address (indexed) exchangeToken, uint256 amount, address executedBy);
```

### `FundsWithdrawn`

_From_ `IBosonDisputeHandler`

```solidity
event FundsWithdrawn(uint256 (indexed) sellerId, address (indexed) withdrawnTo, address (indexed) tokenAddress, uint256 amount, address executedBy);
```

### `GroupCreated`

_From_ `IBosonGroupHandler`

```solidity
event GroupCreated(uint256 (indexed) groupId, uint256 (indexed) sellerId, (uint256, uint256, uint256[]) group, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) condition, address (indexed) executedBy);
```

### `GroupUpdated`

_From_ `IBosonGroupHandler`

```solidity
event GroupUpdated(uint256 (indexed) groupId, uint256 (indexed) sellerId, (uint256, uint256, uint256[]) group, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) condition, address (indexed) executedBy);
```

### `MaxEscalationResponsePeriodChanged`

_From_ `IBosonConfigHandler`

```solidity
event MaxEscalationResponsePeriodChanged(uint256 maxEscalationResponsePeriod, address (indexed) executedBy);
```

### `MaxPremintedVouchersChanged`

_From_ `IBosonConfigHandler`

```solidity
event MaxPremintedVouchersChanged(uint256 maxPremintedVouchers, address (indexed) executedBy);
```

### `MaxResolutionPeriodChanged`

_From_ `IBosonConfigHandler`

```solidity
event MaxResolutionPeriodChanged(uint256 maxResolutionPeriod, address (indexed) executedBy);
```

### `MaxRoyaltyPercentageChanged`

_From_ `IBosonConfigHandler`

```solidity
event MaxRoyaltyPercentageChanged(uint16 maxRoyaltyPercentage, address (indexed) executedBy);
```

### `MaxTotalOfferFeePercentageChanged`

_From_ `IBosonConfigHandler`

```solidity
event MaxTotalOfferFeePercentageChanged(uint16 maxTotalOfferFeePercentage, address (indexed) executedBy);
```

### `MetaTransactionExecuted`

_From_ `IBosonMetaTransactionsHandler`

```solidity
event MetaTransactionExecuted(address (indexed) userAddress, address (indexed) relayerAddress, string (indexed) functionName, uint256 nonce);
```

### `MinDisputePeriodChanged`

_From_ `IBosonConfigHandler`

```solidity
event MinDisputePeriodChanged(uint256 minDisputePeriod, address (indexed) executedBy);
```

### `MinResolutionPeriodChanged`

_From_ `IBosonConfigHandler`

```solidity
event MinResolutionPeriodChanged(uint256 minResolutionPeriod, address (indexed) executedBy);
```

### `MutualizerGasStipendChanged`

_From_ `IBosonConfigHandler`

```solidity
event MutualizerGasStipendChanged(uint256 mutualizerGasStipend, address (indexed) executedBy);
```

### `NonListedOfferVoided`

_From_ `IBosonOfferHandler`

```solidity
event NonListedOfferVoided(bytes32 offerHash, uint256 (indexed) offererId, address (indexed) executedBy);
```

### `OfferCreated`

_From_ `IBosonOfferHandler`

```solidity
event OfferCreated(uint256 (indexed) offerId, uint256 (indexed) sellerId, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) offer, (uint256, uint256, uint256, uint256) offerDates, (uint256, uint256, uint256) offerDurations, (uint256, uint256, uint256, uint256, address) disputeResolutionTerms, (uint256, uint256) offerFees, uint256 (indexed) agentId, address executedBy);
```

### `OfferExtended`

_From_ `IBosonOfferHandler`

```solidity
event OfferExtended(uint256 (indexed) offerId, uint256 (indexed) sellerId, uint256 validUntilDate, address (indexed) executedBy);
```

### `OfferMutualizerUpdated`

_From_ `IBosonOfferHandler`

```solidity
event OfferMutualizerUpdated(uint256 (indexed) offerId, uint256 (indexed) sellerId, address (indexed) newMutualizer, address executedBy);
```

### `OfferRoyaltyInfoUpdated`

_From_ `IBosonOfferHandler`

```solidity
event OfferRoyaltyInfoUpdated(uint256 (indexed) offerId, uint256 (indexed) sellerId, (address[], uint256[]) royaltyInfo, address (indexed) executedBy);
```

### `OfferVoided`

_From_ `IBosonOfferHandler`

```solidity
event OfferVoided(uint256 (indexed) offerId, uint256 (indexed) creatorId, address (indexed) executedBy);
```

### `PriceDiscoveryAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event PriceDiscoveryAddressChanged(address (indexed) priceDiscoveryAddress, address (indexed) executedBy);
```

### `ProtocolAddressChanged`

_From_ `IClientExternalAddressesEvents`

```solidity
event ProtocolAddressChanged(address (indexed) protocol, address (indexed) executedBy);
```

### `ProtocolFeeCollected`

_From_ `IBosonDisputeHandler`

```solidity
event ProtocolFeeCollected(uint256 (indexed) exchangeId, address (indexed) exchangeToken, uint256 amount, address (indexed) executedBy);
```

### `ProtocolFeeFlatBosonChanged`

_From_ `IBosonConfigHandler`

```solidity
event ProtocolFeeFlatBosonChanged(uint256 feeFlatBoson, address (indexed) executedBy);
```

### `ProtocolFeePercentageChanged`

_From_ `IBosonConfigHandler`

```solidity
event ProtocolFeePercentageChanged(uint256 feePercentage, address (indexed) executedBy);
```

### `ProtocolInitialized`

_From_ `IBosonProtocolInitializationHandler`

```solidity
event ProtocolInitialized(string version);
```

### `ProtocolPaused`

_From_ `IBosonPauseHandler`

```solidity
event ProtocolPaused(uint8[] regions, address executedBy);
```

### `ProtocolUnpaused`

_From_ `IBosonPauseHandler`

```solidity
event ProtocolUnpaused(uint8[] regions, address executedBy);
```

### `RangeReserved`

_From_ `IBosonOfferHandler`

```solidity
event RangeReserved(uint256 (indexed) offerId, uint256 (indexed) sellerId, uint256 startExchangeId, uint256 endExchangeId, address owner, address (indexed) executedBy);
```

### `RoyaltyRecipientsChanged`

_From_ `IBosonAccountHandler`

```solidity
event RoyaltyRecipientsChanged(uint256 (indexed) sellerId, (address, uint256)[] royaltyRecipients, address (indexed) executedBy);
```

### `SellerCommitted`

_From_ `IBosonExchangeCommitHandler`

```solidity
event SellerCommitted(uint256 (indexed) offerId, uint256 (indexed) sellerId, uint256 (indexed) exchangeId, (uint256, uint256, uint256, uint256, uint8, address) exchange, (uint256, uint256, uint256, bool) voucher, address executedBy);
```

### `SellerCreated`

_From_ `IBosonAccountHandler`

```solidity
event SellerCreated(uint256 (indexed) sellerId, (uint256, address, address, address, address, bool, string) seller, address voucherCloneAddress, (uint256, uint8) authToken, address (indexed) executedBy);
```

### `SellerUpdateApplied`

_From_ `IBosonAccountHandler`

```solidity
event SellerUpdateApplied(uint256 (indexed) sellerId, (uint256, address, address, address, address, bool, string) seller, (uint256, address, address, address, address, bool, string) pendingSeller, (uint256, uint8) authToken, (uint256, uint8) pendingAuthToken, address (indexed) executedBy);
```

### `SellerUpdatePending`

_From_ `IBosonAccountHandler`

```solidity
event SellerUpdatePending(uint256 (indexed) sellerId, (uint256, address, address, address, address, bool, string) pendingSeller, (uint256, uint8) pendingAuthToken, address (indexed) executedBy);
```

### `TokenAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event TokenAddressChanged(address (indexed) tokenAddress, address (indexed) executedBy);
```

### `TreasuryAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event TreasuryAddressChanged(address (indexed) treasuryAddress, address (indexed) executedBy);
```

### `TwinCreated`

_From_ `IBosonExchangeHandler`

```solidity
event TwinCreated(uint256 (indexed) twinId, uint256 (indexed) sellerId, (uint256, uint256, uint256, uint256, uint256, address, uint8) twin, address (indexed) executedBy);
```

### `TwinDeleted`

_From_ `IBosonExchangeHandler`

```solidity
event TwinDeleted(uint256 (indexed) twinId, uint256 (indexed) sellerId, address (indexed) executedBy);
```

### `TwinTransferFailed`

_From_ `IBosonExchangeHandler`

```solidity
event TwinTransferFailed(uint256 (indexed) twinId, address (indexed) tokenAddress, uint256 (indexed) exchangeId, uint256 tokenId, uint256 amount, address executedBy);
```

### `TwinTransferred`

_From_ `IBosonExchangeHandler`

```solidity
event TwinTransferred(uint256 (indexed) twinId, address (indexed) tokenAddress, uint256 (indexed) exchangeId, uint256 tokenId, uint256 amount, address executedBy);
```

### `TwinTransferSkipped`

_From_ `IBosonExchangeHandler`

```solidity
event TwinTransferSkipped(uint256 (indexed) exchangeId, uint256 twinCount, address (indexed) executedBy);
```

### `Upgraded`

_From_ `IClientExternalAddressesEvents`

```solidity
event Upgraded(address (indexed) implementation, address (indexed) executedBy);
```

### `VoucherBeaconAddressChanged`

_From_ `IBosonConfigHandler`

```solidity
event VoucherBeaconAddressChanged(address (indexed) voucherBeaconAddress, address (indexed) executedBy);
```

### `VoucherCanceled`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherCanceled(uint256 (indexed) offerId, uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `VoucherExpired`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherExpired(uint256 (indexed) offerId, uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `VoucherExtended`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherExtended(uint256 (indexed) offerId, uint256 (indexed) exchangeId, uint256 validUntil, address (indexed) executedBy);
```

### `VoucherRedeemed`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherRedeemed(uint256 (indexed) offerId, uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `VoucherRevoked`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherRevoked(uint256 (indexed) offerId, uint256 (indexed) exchangeId, address (indexed) executedBy);
```

### `VoucherTransferred`

_From_ `IBosonExchangeCommitHandler`

```solidity
event VoucherTransferred(uint256 (indexed) offerId, uint256 (indexed) exchangeId, uint256 (indexed) newBuyerId, address executedBy);
```

## Source

- ABI artifacts: [`boson-protocol-contracts/addresses/abis/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/addresses/abis)
- Event interfaces: [`contracts/interfaces/events/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/contracts/interfaces/events)

## Related

- [Concepts → Eventing & indexing](/concepts/eventing) — how to subscribe.
- [Build → Marketplace operators → Webhooks & events](/build/marketplace/webhooks).
- [Recipes → Webhook server](/recipes/webhook-server).

---

# Reference — Contracts: Diamond facets

URL: https://www.bosonprotocol.io/docs/reference/contracts/facets

> Handler facet interfaces — every external function the Diamond exposes.

# Diamond facets

:::info
**Generated from `boson-protocol-contracts/addresses/abis/polygon`. Edit the Solidity sources, not this page.**
:::

The Diamond is an [EIP-2535](https://eips.ethereum.org/EIPS/eip-2535) proxy. Each handler facet implements one domain. All functions are reachable through the single Diamond address — cast it to whichever interface you need.

## Summary

| Facet | Functions | Events | Errors |
| --- | --- | --- | --- |
| `IBosonAccountHandler` | 34 | 16 | 181 |
| `IBosonAgentHandler` | 3 | 0 | 0 |
| `IBosonBundleHandler` | 5 | 1 | 181 |
| `IBosonBuyerHandler` | 3 | 0 | 0 |
| `IBosonConfigHandler` | 38 | 19 | 181 |
| `IBosonDisputeHandler` | 14 | 17 | 181 |
| `IBosonDisputeResolverHandler` | 10 | 0 | 0 |
| `IBosonExchangeCommitHandler` | 6 | 19 | 181 |
| `IBosonExchangeHandler` | 15 | 24 | 181 |
| `IBosonExchangeManagementHandler` | 15 | 16 | 181 |
| `IBosonFundsHandler` | 7 | 8 | 181 |
| `IBosonGroupHandler` | 6 | 2 | 181 |
| `IBosonMetaTransactionsHandler` | 5 | 2 | 181 |
| `IBosonOfferHandler` | 17 | 7 | 181 |
| `IBosonOrchestrationHandler` | 17 | 31 | 181 |
| `IBosonPauseHandler` | 3 | 2 | 181 |
| `IBosonPriceDiscoveryHandler` | 1 | 24 | 181 |
| `IBosonProtocolInitializationHandler` | 1 | 20 | 181 |
| `IBosonSellerHandler` | 17 | 0 | 0 |
| `IBosonSequentialCommitHandler` | 1 | 19 | 181 |
| `IBosonTwinHandler` | 4 | 5 | 181 |

## Details

### `IBosonAccountHandler`

_Source: [`contracts/interfaces/handlers/IBosonAccountHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonAccountHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `addFeesToDisputeResolver` | `(uint256 _disputeResolverId, (address, string, uint256)[] _disputeResolverFees)` | — | `nonpayable` |
| `addRoyaltyRecipients` | `(uint256 _sellerId, (address, uint256)[] _royaltyRecipients)` | — | `nonpayable` |
| `addSellersToAllowList` | `(uint256 _disputeResolverId, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `areSellersAllowed` | `(uint256 _disputeResolverId, uint256[] _sellerIds)` | `(bool[])` | `view` |
| `calculateCollectionAddress` | `(uint256 _sellerId, bytes32 _collectionSalt)` | `(address, bool)` | `view` |
| `createAgent` | `((uint256, uint256, address, bool) _agent)` | — | `nonpayable` |
| `createBuyer` | `((uint256, address, bool) _buyer)` | — | `nonpayable` |
| `createDisputeResolver` | `((uint256, uint256, address, address, address, address, string, bool) _disputeResolver, (address, string, uint256)[] _disputeResolverFees, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `createNewCollection` | `(string _externalId, (string, uint256, bytes32) _voucherInitValues)` | — | `nonpayable` |
| `createSeller` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues)` | — | `nonpayable` |
| `getAgent` | `(uint256 _agentId)` | `(bool, (uint256, uint256, address, bool))` | `view` |
| `getBuyer` | `(uint256 _buyerId)` | `(bool, (uint256, address, bool))` | `view` |
| `getDisputeResolver` | `(uint256 _disputeResolverId)` | `(bool, (uint256, uint256, address, address, address, address, string, bool), (address, string, uint256)[], uint256[])` | `view` |
| `getDisputeResolverByAddress` | `(address _associatedAddress)` | `(bool, (uint256, uint256, address, address, address, address, string, bool), (address, string, uint256)[], uint256[])` | `view` |
| `getNextAccountId` | `()` | `(uint256)` | `view` |
| `getRoyaltyRecipients` | `(uint256 _sellerId)` | `((address, uint256)[])` | `view` |
| `getSeller` | `(uint256 _sellerId)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellerByAddress` | `(address _associatedAddress)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellerByAuthToken` | `((uint256, uint8) _associatedAuthToken)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellersCollectionCount` | `(uint256 _sellerId)` | `(uint256)` | `view` |
| `getSellersCollections` | `(uint256 _sellerId)` | `(address, (address, string)[])` | `view` |
| `getSellersCollectionsPaginated` | `(uint256 _sellerId, uint256 _limit, uint256 _offset)` | `(address, (address, string)[])` | `view` |
| `isSellerSaltAvailable` | `(address _adminAddres, bytes32 _salt)` | `(bool)` | `view` |
| `optInToDisputeResolverUpdate` | `(uint256 _disputeResolverId, uint8[] _fieldsToUpdate)` | — | `nonpayable` |
| `optInToSellerUpdate` | `(uint256 _sellerId, uint8[] _fieldsToUpdate)` | — | `nonpayable` |
| `removeFeesFromDisputeResolver` | `(uint256 _disputeResolverId, address[] _feeTokenAddresses)` | — | `nonpayable` |
| `removeRoyaltyRecipients` | `(uint256 _sellerId, uint256[] _royaltyRecipientIds)` | — | `nonpayable` |
| `removeSellersFromAllowList` | `(uint256 _disputeResolverId, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `updateAgent` | `((uint256, uint256, address, bool) _agent)` | — | `nonpayable` |
| `updateBuyer` | `((uint256, address, bool) _buyer)` | — | `nonpayable` |
| `updateDisputeResolver` | `((uint256, uint256, address, address, address, address, string, bool) _disputeResolver)` | — | `nonpayable` |
| `updateRoyaltyRecipients` | `(uint256 _sellerId, uint256[] _royaltyRecipientIds, (address, uint256)[] _royaltyRecipients)` | — | `nonpayable` |
| `updateSeller` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint8) _authToken)` | — | `nonpayable` |
| `updateSellerSalt` | `(uint256 _sellerId, bytes32 _newSalt)` | — | `nonpayable` |

### `IBosonAgentHandler`

_Source: [`contracts/interfaces/handlers/IBosonAgentHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonAgentHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createAgent` | `((uint256, uint256, address, bool) _agent)` | — | `nonpayable` |
| `getAgent` | `(uint256 _agentId)` | `(bool, (uint256, uint256, address, bool))` | `view` |
| `updateAgent` | `((uint256, uint256, address, bool) _agent)` | — | `nonpayable` |

### `IBosonBundleHandler`

_Source: [`contracts/interfaces/handlers/IBosonBundleHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonBundleHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createBundle` | `((uint256, uint256, uint256[], uint256[]) _bundle)` | — | `nonpayable` |
| `getBundle` | `(uint256 _bundleId)` | `(bool, (uint256, uint256, uint256[], uint256[]))` | `view` |
| `getBundleIdByOffer` | `(uint256 _offerId)` | `(bool, uint256)` | `view` |
| `getBundleIdByTwin` | `(uint256 _twinId)` | `(bool, uint256)` | `view` |
| `getNextBundleId` | `()` | `(uint256)` | `view` |

### `IBosonBuyerHandler`

_Source: [`contracts/interfaces/handlers/IBosonBuyerHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonBuyerHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createBuyer` | `((uint256, address, bool) _buyer)` | — | `nonpayable` |
| `getBuyer` | `(uint256 _buyerId)` | `(bool, (uint256, address, bool))` | `view` |
| `updateBuyer` | `((uint256, address, bool) _buyer)` | — | `nonpayable` |

### `IBosonConfigHandler`

_Source: [`contracts/interfaces/handlers/IBosonConfigHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonConfigHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `getAccessControllerAddress` | `()` | `(address)` | `view` |
| `getAuthTokenContract` | `(uint8 _authTokenType)` | `(address)` | `view` |
| `getBeaconProxyAddress` | `()` | `(address)` | `view` |
| `getBuyerEscalationDepositPercentage` | `()` | `(uint256)` | `view` |
| `getMaxEscalationResponsePeriod` | `()` | `(uint256)` | `view` |
| `getMaxResolutionPeriod` | `()` | `(uint256)` | `view` |
| `getMaxRoyaltyPercentage` | `()` | `(uint16)` | `view` |
| `getMaxTotalOfferFeePercentage` | `()` | `(uint16)` | `view` |
| `getMinDisputePeriod` | `()` | `(uint256)` | `view` |
| `getMinResolutionPeriod` | `()` | `(uint256)` | `view` |
| `getMutualizerGasStipend` | `()` | `(uint256)` | `view` |
| `getPriceDiscoveryAddress` | `()` | `(address)` | `view` |
| `getProtocolFee` | `(address _exchangeToken, uint256 _price)` | `(uint256)` | `view` |
| `getProtocolFeeFlatBoson` | `()` | `(uint256)` | `view` |
| `getProtocolFeePercentage` | `()` | `(uint256)` | `view` |
| `getProtocolFeePercentage` | `(address _exchangeToken, uint256 _price)` | `(uint256)` | `view` |
| `getProtocolFeeTable` | `(address _tokenAddress)` | `(uint256[], uint256[])` | `view` |
| `getTokenAddress` | `()` | `(address)` | `view` |
| `getTreasuryAddress` | `()` | `(address)` | `view` |
| `getVoucherBeaconAddress` | `()` | `(address)` | `view` |
| `setAccessControllerAddress` | `(address _accessControllerAddress)` | — | `nonpayable` |
| `setAuthTokenContract` | `(uint8 _authTokenType, address _authTokenContract)` | — | `nonpayable` |
| `setBeaconProxyAddress` | `(address _beaconProxyAddress)` | — | `nonpayable` |
| `setBuyerEscalationDepositPercentage` | `(uint256 _buyerEscalationDepositPercentage)` | — | `nonpayable` |
| `setMaxEscalationResponsePeriod` | `(uint256 _maxEscalationResponsePeriod)` | — | `nonpayable` |
| `setMaxResolutionPeriod` | `(uint256 _maxResolutionPeriod)` | — | `nonpayable` |
| `setMaxRoyaltyPercentage` | `(uint16 _maxRoyaltyPercentage)` | — | `nonpayable` |
| `setMaxTotalOfferFeePercentage` | `(uint16 _maxTotalOfferFeePercentage)` | — | `nonpayable` |
| `setMinDisputePeriod` | `(uint256 _minDisputePeriod)` | — | `nonpayable` |
| `setMinResolutionPeriod` | `(uint256 _minResolutionPeriod)` | — | `nonpayable` |
| `setMutualizerGasStipend` | `(uint256 _mutualizerGasStipend)` | — | `nonpayable` |
| `setPriceDiscoveryAddress` | `(address _priceDiscovery)` | — | `nonpayable` |
| `setProtocolFeeFlatBoson` | `(uint256 _protocolFeeFlatBoson)` | — | `nonpayable` |
| `setProtocolFeePercentage` | `(uint256 _protocolFeePercentage)` | — | `nonpayable` |
| `setProtocolFeeTable` | `(address _tokenAddress, uint256[] _priceRanges, uint256[] _feePercentages)` | — | `nonpayable` |
| `setTokenAddress` | `(address _tokenAddress)` | — | `nonpayable` |
| `setTreasuryAddress` | `(address _treasuryAddress)` | — | `nonpayable` |
| `setVoucherBeaconAddress` | `(address _voucherBeaconAddress)` | — | `nonpayable` |

### `IBosonDisputeHandler`

_Source: [`contracts/interfaces/handlers/IBosonDisputeHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonDisputeHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `decideDispute` | `(uint256 _exchangeId, uint256 _buyerPercent)` | — | `nonpayable` |
| `escalateDispute` | `(uint256 _exchangeId)` | — | `payable` |
| `expireDispute` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `expireDisputeBatch` | `(uint256[] _exchangeIds)` | — | `nonpayable` |
| `expireEscalatedDispute` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `extendDisputeTimeout` | `(uint256 _exchangeId, uint256 _newDisputeTimeout)` | — | `nonpayable` |
| `getDispute` | `(uint256 _exchangeId)` | `(bool, (uint256, uint256, uint8), (uint256, uint256, uint256, uint256))` | `view` |
| `getDisputeState` | `(uint256 _exchangeId)` | `(bool, uint8)` | `view` |
| `getDisputeTimeout` | `(uint256 _exchangeId)` | `(bool, uint256)` | `view` |
| `isDisputeFinalized` | `(uint256 _exchangeId)` | `(bool, bool)` | `view` |
| `raiseDispute` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `refuseEscalatedDispute` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `resolveDispute` | `(uint256 _exchangeId, uint256 _buyerPercent, bytes _signature)` | — | `nonpayable` |
| `retractDispute` | `(uint256 _exchangeId)` | — | `nonpayable` |

### `IBosonDisputeResolverHandler`

_Source: [`contracts/interfaces/handlers/IBosonDisputeResolverHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonDisputeResolverHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `addFeesToDisputeResolver` | `(uint256 _disputeResolverId, (address, string, uint256)[] _disputeResolverFees)` | — | `nonpayable` |
| `addSellersToAllowList` | `(uint256 _disputeResolverId, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `areSellersAllowed` | `(uint256 _disputeResolverId, uint256[] _sellerIds)` | `(bool[])` | `view` |
| `createDisputeResolver` | `((uint256, uint256, address, address, address, address, string, bool) _disputeResolver, (address, string, uint256)[] _disputeResolverFees, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `getDisputeResolver` | `(uint256 _disputeResolverId)` | `(bool, (uint256, uint256, address, address, address, address, string, bool), (address, string, uint256)[], uint256[])` | `view` |
| `getDisputeResolverByAddress` | `(address _associatedAddress)` | `(bool, (uint256, uint256, address, address, address, address, string, bool), (address, string, uint256)[], uint256[])` | `view` |
| `optInToDisputeResolverUpdate` | `(uint256 _disputeResolverId, uint8[] _fieldsToUpdate)` | — | `nonpayable` |
| `removeFeesFromDisputeResolver` | `(uint256 _disputeResolverId, address[] _feeTokenAddresses)` | — | `nonpayable` |
| `removeSellersFromAllowList` | `(uint256 _disputeResolverId, uint256[] _sellerAllowList)` | — | `nonpayable` |
| `updateDisputeResolver` | `((uint256, uint256, address, address, address, address, string, bool) _disputeResolver)` | — | `nonpayable` |

### `IBosonExchangeCommitHandler`

_Source: [`contracts/interfaces/handlers/IBosonExchangeCommitHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonExchangeCommitHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `commitToBuyerOffer` | `(uint256 _offerId, (uint256, (address[], uint256[]), address) _sellerParams)` | — | `payable` |
| `commitToConditionalOffer` | `(address _buyer, uint256 _offerId, uint256 _tokenId)` | — | `payable` |
| `commitToOffer` | `(address _buyer, uint256 _offerId)` | — | `payable` |
| `createOfferAndCommit` | `(((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256), (uint256, uint256, uint256, uint256), (uint256, uint256, uint256), (uint256, address), (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool) _fullOffer, address _offerCreator, address _committer, bytes _signature, uint256 _conditionalTokenId, (uint256, (address[], uint256[]), address) _sellerParams)` | — | `payable` |
| `isEligibleToCommit` | `(address _buyer, uint256 _offerId, uint256 _tokenId)` | `(bool, uint256, uint256)` | `view` |
| `onPremintedVoucherTransferred` | `(uint256 _tokenId, address _to, address _from, address _rangeOwner)` | `(bool)` | `nonpayable` |

### `IBosonExchangeHandler`

_Source: [`contracts/interfaces/handlers/IBosonExchangeHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonExchangeHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `cancelVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `completeExchange` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `completeExchangeBatch` | `(uint256[] _exchangeIds)` | — | `nonpayable` |
| `expireVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `extendVoucher` | `(uint256 _exchangeId, uint256 _validUntilDate)` | — | `nonpayable` |
| `getEIP2981Royalties` | `(uint256 _queryId, bool _isExchangeId)` | `(address, uint256)` | `view` |
| `getExchange` | `(uint256 _exchangeId)` | `(bool, (uint256, uint256, uint256, uint256, uint8, address), (uint256, uint256, uint256, bool))` | `view` |
| `getExchangeState` | `(uint256 _exchangeId)` | `(bool, uint8)` | `view` |
| `getNextExchangeId` | `()` | `(uint256)` | `view` |
| `getReceipt` | `(uint256 _exchangeId)` | `((uint256, uint256, uint256, uint256, uint256, uint256, uint256, (uint256, uint256), uint256, address, uint256, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool, uint256, uint256, uint256, uint8, (uint256, uint256, uint256, address, uint8)[]))` | `view` |
| `getRoyalties` | `(uint256 _tokenId)` | `(address[], uint256[])` | `view` |
| `isExchangeFinalized` | `(uint256 _exchangeId)` | `(bool, bool)` | `view` |
| `onVoucherTransferred` | `(uint256 _tokenId, address _newBuyer)` | — | `nonpayable` |
| `redeemVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `revokeVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |

### `IBosonExchangeManagementHandler`

_Source: [`contracts/interfaces/handlers/IBosonExchangeManagementHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonExchangeManagementHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `cancelVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `completeExchange` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `completeExchangeBatch` | `(uint256[] _exchangeIds)` | — | `nonpayable` |
| `expireVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `extendVoucher` | `(uint256 _exchangeId, uint256 _validUntilDate)` | — | `nonpayable` |
| `getEIP2981Royalties` | `(uint256 _queryId, bool _isExchangeId)` | `(address, uint256)` | `view` |
| `getExchange` | `(uint256 _exchangeId)` | `(bool, (uint256, uint256, uint256, uint256, uint8, address), (uint256, uint256, uint256, bool))` | `view` |
| `getExchangeState` | `(uint256 _exchangeId)` | `(bool, uint8)` | `view` |
| `getNextExchangeId` | `()` | `(uint256)` | `view` |
| `getReceipt` | `(uint256 _exchangeId)` | `((uint256, uint256, uint256, uint256, uint256, uint256, uint256, (uint256, uint256), uint256, address, uint256, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool, uint256, uint256, uint256, uint8, (uint256, uint256, uint256, address, uint8)[]))` | `view` |
| `getRoyalties` | `(uint256 _tokenId)` | `(address[], uint256[])` | `view` |
| `isExchangeFinalized` | `(uint256 _exchangeId)` | `(bool, bool)` | `view` |
| `onVoucherTransferred` | `(uint256 _tokenId, address _newBuyer)` | — | `nonpayable` |
| `redeemVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |
| `revokeVoucher` | `(uint256 _exchangeId)` | — | `nonpayable` |

### `IBosonFundsHandler`

_Source: [`contracts/interfaces/handlers/IBosonFundsHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonFundsHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `depositFunds` | `(uint256 _entityId, address _tokenAddress, uint256 _amount)` | — | `payable` |
| `getAllAvailableFunds` | `(uint256 _entityId)` | `((address, string, uint256)[])` | `view` |
| `getAvailableFunds` | `(uint256 _entityId, address[] _tokenList)` | `((address, string, uint256)[])` | `view` |
| `getTokenList` | `(uint256 _entityId)` | `(address[])` | `view` |
| `getTokenListPaginated` | `(uint256 _entityId, uint256 _limit, uint256 _offset)` | `(address[])` | `view` |
| `withdrawFunds` | `(uint256 _entityId, address[] _tokenList, uint256[] _tokenAmounts)` | — | `nonpayable` |
| `withdrawProtocolFees` | `(address[] _tokenList, uint256[] _tokenAmounts)` | — | `nonpayable` |

### `IBosonGroupHandler`

_Source: [`contracts/interfaces/handlers/IBosonGroupHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonGroupHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `addOffersToGroup` | `(uint256 _groupId, uint256[] _offerIds)` | — | `nonpayable` |
| `createGroup` | `((uint256, uint256, uint256[]) _group, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition)` | — | `nonpayable` |
| `getGroup` | `(uint256 _groupId)` | `(bool, (uint256, uint256, uint256[]), (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256))` | `view` |
| `getNextGroupId` | `()` | `(uint256)` | `view` |
| `removeOffersFromGroup` | `(uint256 _groupId, uint256[] _offerIds)` | — | `nonpayable` |
| `setGroupCondition` | `(uint256 _groupId, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition)` | — | `nonpayable` |

### `IBosonMetaTransactionsHandler`

_Source: [`contracts/interfaces/handlers/IBosonMetaTransactionsHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonMetaTransactionsHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `executeMetaTransaction` | `(address _userAddress, string _functionName, bytes _functionSignature, uint256 _nonce, bytes _signature)` | `(bytes)` | `payable` |
| `isFunctionAllowlisted` | `(string _functionName)` | `(bool)` | `view` |
| `isFunctionAllowlisted` | `(bytes32 _functionNameHash)` | `(bool)` | `view` |
| `isUsedNonce` | `(address _associatedAddress, uint256 _nonce)` | `(bool)` | `view` |
| `setAllowlistedFunctions` | `(bytes32[] _functionNameHashes, bool _isAllowlisted)` | — | `nonpayable` |

### `IBosonOfferHandler`

_Source: [`contracts/interfaces/handlers/IBosonOfferHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonOfferHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createOffer` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createOfferBatch` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256)[] _offers, (uint256, uint256, uint256, uint256)[] _offerDates, (uint256, uint256, uint256)[] _offerDurations, (uint256, address)[] _drParameters, uint256[] _agentIds, uint256[] _feeLimits)` | — | `nonpayable` |
| `extendOffer` | `(uint256 _offerId, uint256 _validUntilDate)` | — | `nonpayable` |
| `extendOfferBatch` | `(uint256[] _offerIds, uint256 _validUntilDate)` | — | `nonpayable` |
| `getAgentIdByOffer` | `(uint256 _offerId)` | `(bool, uint256)` | `view` |
| `getNextOfferId` | `()` | `(uint256)` | `view` |
| `getOffer` | `(uint256 _offerId)` | `(bool, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256), (uint256, uint256, uint256, uint256), (uint256, uint256, uint256), (uint256, uint256, uint256, uint256, address), (uint256, uint256))` | `view` |
| `getOfferHash` | `(((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256), (uint256, uint256, uint256, uint256), (uint256, uint256, uint256), (uint256, address), (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool) _fullOffer)` | `(bytes32)` | `view` |
| `isOfferVoided` | `(uint256 _offerId)` | `(bool, bool)` | `view` |
| `reserveRange` | `(uint256 _offerId, uint256 _length, address _to)` | — | `nonpayable` |
| `updateOfferMutualizer` | `(uint256 _offerId, address _newMutualizer)` | — | `nonpayable` |
| `updateOfferRoyaltyRecipients` | `(uint256 _offerId, (address[], uint256[]) _royaltyInfo)` | — | `nonpayable` |
| `updateOfferRoyaltyRecipientsBatch` | `(uint256[] _offerIds, (address[], uint256[]) _royaltyInfo)` | — | `nonpayable` |
| `voidNonListedOffer` | `(((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256), (uint256, uint256, uint256, uint256), (uint256, uint256, uint256), (uint256, address), (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool) _fullOffer)` | — | `nonpayable` |
| `voidNonListedOfferBatch` | `(((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256), (uint256, uint256, uint256, uint256), (uint256, uint256, uint256), (uint256, address), (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256), uint256, uint256, bool)[] _fullOffers)` | — | `nonpayable` |
| `voidOffer` | `(uint256 _offerId)` | — | `nonpayable` |
| `voidOfferBatch` | `(uint256[] _offerIds)` | — | `nonpayable` |

### `IBosonOrchestrationHandler`

_Source: [`contracts/interfaces/handlers/IBosonOrchestrationHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonOrchestrationHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createOfferAddToGroup` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, uint256 _groupId, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createOfferAndTwinWithBundle` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createOfferWithCondition` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createOfferWithConditionAndTwinAndBundle` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createPremintedOfferAddToGroup` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, uint256 _groupId, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createPremintedOfferAndTwinWithBundle` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createPremintedOfferWithCondition` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createPremintedOfferWithConditionAndTwinAndBundle` | `((uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndOffer` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndOfferAndTwinWithBundle` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndOfferWithCondition` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndOfferWithConditionAndTwinAndBundle` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndPremintedOffer` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndPremintedOfferAndTwinWithBundle` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndPremintedOfferWithCondition` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `createSellerAndPremintedOfferWithConditionAndTwinAndBundle` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint256, uint256, uint256, uint256, uint256, address, uint8, uint8, string, string, bool, uint256, (address[], uint256[])[], uint256) _offer, (uint256, uint256, uint256, uint256) _offerDates, (uint256, uint256, uint256) _offerDurations, (uint256, address) _drParameters, (uint256, address) _premintParameters, (uint8, uint8, address, uint8, uint256, uint256, uint256, uint256) _condition, (uint256, uint256, uint256, uint256, uint256, address, uint8) _twin, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues, uint256 _agentId, uint256 _feeLimit)` | — | `nonpayable` |
| `raiseAndEscalateDispute` | `(uint256 _exchangeId)` | — | `payable` |

### `IBosonPauseHandler`

_Source: [`contracts/interfaces/handlers/IBosonPauseHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonPauseHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `getPausedRegions` | `()` | `(uint8[])` | `view` |
| `pause` | `(uint8[] _regions)` | — | `nonpayable` |
| `unpause` | `(uint8[] _regions)` | — | `nonpayable` |

### `IBosonPriceDiscoveryHandler`

_Source: [`contracts/interfaces/handlers/IBosonPriceDiscoveryHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonPriceDiscoveryHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `commitToPriceDiscoveryOffer` | `(address _buyer, uint256 _tokenIdOrOfferId, (uint256, uint8, address, address, bytes) _priceDiscovery)` | — | `payable` |

### `IBosonProtocolInitializationHandler`

_Source: [`contracts/interfaces/handlers/IBosonProtocolInitializationHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonProtocolInitializationHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `getVersion` | `()` | `(string)` | `view` |

### `IBosonSellerHandler`

_Source: [`contracts/interfaces/handlers/IBosonSellerHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonSellerHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `addRoyaltyRecipients` | `(uint256 _sellerId, (address, uint256)[] _royaltyRecipients)` | — | `nonpayable` |
| `calculateCollectionAddress` | `(uint256 _sellerId, bytes32 _collectionSalt)` | `(address, bool)` | `view` |
| `createNewCollection` | `(string _externalId, (string, uint256, bytes32) _voucherInitValues)` | — | `nonpayable` |
| `createSeller` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint8) _authToken, (string, uint256, bytes32) _voucherInitValues)` | — | `nonpayable` |
| `getRoyaltyRecipients` | `(uint256 _sellerId)` | `((address, uint256)[])` | `view` |
| `getSeller` | `(uint256 _sellerId)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellerByAddress` | `(address _associatedAddress)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellerByAuthToken` | `((uint256, uint8) _associatedAuthToken)` | `(bool, (uint256, address, address, address, address, bool, string), (uint256, uint8))` | `view` |
| `getSellersCollectionCount` | `(uint256 _sellerId)` | `(uint256)` | `view` |
| `getSellersCollections` | `(uint256 _sellerId)` | `(address, (address, string)[])` | `view` |
| `getSellersCollectionsPaginated` | `(uint256 _sellerId, uint256 _limit, uint256 _offset)` | `(address, (address, string)[])` | `view` |
| `isSellerSaltAvailable` | `(address _adminAddres, bytes32 _salt)` | `(bool)` | `view` |
| `optInToSellerUpdate` | `(uint256 _sellerId, uint8[] _fieldsToUpdate)` | — | `nonpayable` |
| `removeRoyaltyRecipients` | `(uint256 _sellerId, uint256[] _royaltyRecipientIds)` | — | `nonpayable` |
| `updateRoyaltyRecipients` | `(uint256 _sellerId, uint256[] _royaltyRecipientIds, (address, uint256)[] _royaltyRecipients)` | — | `nonpayable` |
| `updateSeller` | `((uint256, address, address, address, address, bool, string) _seller, (uint256, uint8) _authToken)` | — | `nonpayable` |
| `updateSellerSalt` | `(uint256 _sellerId, bytes32 _newSalt)` | — | `nonpayable` |

### `IBosonSequentialCommitHandler`

_Source: [`contracts/interfaces/handlers/IBosonSequentialCommitHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonSequentialCommitHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `sequentialCommitToOffer` | `(address _buyer, uint256 _exchangeId, (uint256, uint8, address, address, bytes) _priceDiscovery)` | — | `payable` |

### `IBosonTwinHandler`

_Source: [`contracts/interfaces/handlers/IBosonTwinHandler.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/interfaces/handlers/IBosonTwinHandler.sol)_

| Function | Inputs | Outputs | Mutability |
| --- | --- | --- | --- |
| `createTwin` | `((uint256, uint256, uint256, uint256, uint256, address, uint8) _twin)` | — | `nonpayable` |
| `getNextTwinId` | `()` | `(uint256)` | `view` |
| `getTwin` | `(uint256 _twinId)` | `(bool, (uint256, uint256, uint256, uint256, uint256, address, uint8))` | `view` |
| `removeTwin` | `(uint256 _twinId)` | — | `nonpayable` |

## Source

- ABI artifacts: [`boson-protocol-contracts/addresses/abis/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/addresses/abis)
- Handler interfaces: [`contracts/interfaces/handlers/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/contracts/interfaces/handlers)

## Related

- [Concepts → Architecture](/concepts/architecture).
- [Quickstart → Call Boson from Solidity](/quickstart/solidity).

---

# Reference — Contracts: Structs

URL: https://www.bosonprotocol.io/docs/reference/contracts/structs

> Every named struct exposed by the Boson Diamond, reconstructed from the ABI.

# Structs

:::info
**Generated from `boson-protocol-contracts/addresses/abis/polygon`. Edit the Solidity sources, not this page.**
:::

These structs surface in the function inputs and outputs of the Diamond's facets. Names match the on-chain Solidity declarations. Nested structs reference each other by short name.

## `BosonTypes` (31)

### `Agent`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `feePercentage` | `uint256` |
| `wallet` | `address` |
| `active` | `bool` |

### `AuthToken`

| Field | Type |
| --- | --- |
| `tokenId` | `uint256` |
| `tokenType` | `AuthTokenType (enum)` |

### `Bundle`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `sellerId` | `uint256` |
| `offerIds` | `uint256[]` |
| `twinIds` | `uint256[]` |

### `Buyer`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `wallet` | `address` |
| `active` | `bool` |

### `Collection`

| Field | Type |
| --- | --- |
| `collectionAddress` | `address` |
| `externalId` | `string` |

### `Condition`

| Field | Type |
| --- | --- |
| `method` | `EvaluationMethod (enum)` |
| `tokenType` | `TokenType (enum)` |
| `tokenAddress` | `address` |
| `gating` | `GatingType (enum)` |
| `minTokenId` | `uint256` |
| `threshold` | `uint256` |
| `maxCommits` | `uint256` |
| `maxTokenId` | `uint256` |

### `Dispute`

| Field | Type |
| --- | --- |
| `exchangeId` | `uint256` |
| `buyerPercent` | `uint256` |
| `state` | `DisputeState (enum)` |

### `DisputeDates`

| Field | Type |
| --- | --- |
| `disputed` | `uint256` |
| `escalated` | `uint256` |
| `finalized` | `uint256` |
| `timeout` | `uint256` |

### `DisputeResolutionTerms`

| Field | Type |
| --- | --- |
| `disputeResolverId` | `uint256` |
| `escalationResponsePeriod` | `uint256` |
| `feeAmount` | `uint256` |
| `buyerEscalationDeposit` | `uint256` |
| `mutualizerAddress` | `address` |

### `DisputeResolver`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `escalationResponsePeriod` | `uint256` |
| `assistant` | `address` |
| `admin` | `address` |
| `clerk` | `address` |
| `treasury` | `address` |
| `metadataUri` | `string` |
| `active` | `bool` |

### `DisputeResolverFee`

| Field | Type |
| --- | --- |
| `tokenAddress` | `address` |
| `tokenName` | `string` |
| `feeAmount` | `uint256` |

### `DRParameters`

| Field | Type |
| --- | --- |
| `disputeResolverId` | `uint256` |
| `mutualizerAddress` | `address` |

### `Exchange`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `offerId` | `uint256` |
| `buyerId` | `uint256` |
| `finalizedDate` | `uint256` |
| `state` | `ExchangeState (enum)` |
| `mutualizerAddress` | `address` |

### `FullOffer`

| Field | Type |
| --- | --- |
| `offer` | `Offer` |
| `offerDates` | `OfferDates` |
| `offerDurations` | `OfferDurations` |
| `drParameters` | `DRParameters` |
| `condition` | `Condition` |
| `agentId` | `uint256` |
| `feeLimit` | `uint256` |
| `useDepositedFunds` | `bool` |

### `Funds`

| Field | Type |
| --- | --- |
| `tokenAddress` | `address` |
| `tokenName` | `string` |
| `availableAmount` | `uint256` |

### `Group`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `sellerId` | `uint256` |
| `offerIds` | `uint256[]` |

### `Offer`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `sellerId` | `uint256` |
| `price` | `uint256` |
| `sellerDeposit` | `uint256` |
| `buyerCancelPenalty` | `uint256` |
| `quantityAvailable` | `uint256` |
| `exchangeToken` | `address` |
| `priceType` | `PriceType (enum)` |
| `creator` | `OfferCreator (enum)` |
| `metadataUri` | `string` |
| `metadataHash` | `string` |
| `voided` | `bool` |
| `collectionIndex` | `uint256` |
| `royaltyInfo` | `RoyaltyInfo[]` |
| `buyerId` | `uint256` |

### `OfferDates`

| Field | Type |
| --- | --- |
| `validFrom` | `uint256` |
| `validUntil` | `uint256` |
| `voucherRedeemableFrom` | `uint256` |
| `voucherRedeemableUntil` | `uint256` |

### `OfferDurations`

| Field | Type |
| --- | --- |
| `disputePeriod` | `uint256` |
| `voucherValid` | `uint256` |
| `resolutionPeriod` | `uint256` |

### `OfferFees`

| Field | Type |
| --- | --- |
| `protocolFee` | `uint256` |
| `agentFee` | `uint256` |

### `PremintParameters`

| Field | Type |
| --- | --- |
| `reservedRangeLength` | `uint256` |
| `to` | `address` |

### `PriceDiscovery`

| Field | Type |
| --- | --- |
| `price` | `uint256` |
| `side` | `Side (enum)` |
| `priceDiscoveryContract` | `address` |
| `conduit` | `address` |
| `priceDiscoveryData` | `bytes` |

### `Receipt`

| Field | Type |
| --- | --- |
| `exchangeId` | `uint256` |
| `offerId` | `uint256` |
| `buyerId` | `uint256` |
| `sellerId` | `uint256` |
| `price` | `uint256` |
| `sellerDeposit` | `uint256` |
| `buyerCancelPenalty` | `uint256` |
| `offerFees` | `OfferFees` |
| `agentId` | `uint256` |
| `exchangeToken` | `address` |
| `finalizedDate` | `uint256` |
| `condition` | `Condition` |
| `committedDate` | `uint256` |
| `redeemedDate` | `uint256` |
| `voucherExpired` | `bool` |
| `disputeResolverId` | `uint256` |
| `disputedDate` | `uint256` |
| `escalatedDate` | `uint256` |
| `disputeState` | `DisputeState (enum)` |
| `twinReceipts` | `TwinReceipt[]` |

### `RoyaltyInfo`

| Field | Type |
| --- | --- |
| `recipients` | `address[]` |
| `bps` | `uint256[]` |

### `RoyaltyRecipientInfo`

| Field | Type |
| --- | --- |
| `wallet` | `address` |
| `minRoyaltyPercentage` | `uint256` |

### `Seller`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `assistant` | `address` |
| `admin` | `address` |
| `clerk` | `address` |
| `treasury` | `address` |
| `active` | `bool` |
| `metadataUri` | `string` |

### `SellerOfferParams`

| Field | Type |
| --- | --- |
| `collectionIndex` | `uint256` |
| `royaltyInfo` | `RoyaltyInfo` |
| `mutualizerAddress` | `address` |

### `Twin`

| Field | Type |
| --- | --- |
| `id` | `uint256` |
| `sellerId` | `uint256` |
| `amount` | `uint256` |
| `supplyAvailable` | `uint256` |
| `tokenId` | `uint256` |
| `tokenAddress` | `address` |
| `tokenType` | `TokenType (enum)` |

### `TwinReceipt`

| Field | Type |
| --- | --- |
| `twinId` | `uint256` |
| `tokenId` | `uint256` |
| `amount` | `uint256` |
| `tokenAddress` | `address` |
| `tokenType` | `TokenType (enum)` |

### `Voucher`

| Field | Type |
| --- | --- |
| `committedDate` | `uint256` |
| `validUntilDate` | `uint256` |
| `redeemedDate` | `uint256` |
| `expired` | `bool` |

### `VoucherInitValues`

| Field | Type |
| --- | --- |
| `contractURI` | `string` |
| `royaltyPercentage` | `uint256` |
| `collectionSalt` | `bytes32` |

## Source

- ABI artifacts: [`boson-protocol-contracts/addresses/abis/`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/addresses/abis)
- Solidity origin (for full NatSpec, enum values, etc.): [`contracts/domain/BosonTypes.sol`](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/contracts/domain/BosonTypes.sol)

## Related

- [Reference → Contracts → Diamond facets](/reference/contracts/facets) — which facet takes / returns each struct.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Accounts

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/accounts

> Public methods on the Accounts mixin of @bosonprotocol/core-sdk.

# `Accounts` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `AccountsMixin`_

_Source: [`packages/core-sdk/src/accounts/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/accounts/mixin.ts)_



## Methods (33)

`addFeesToDisputeResolver`, `addRoyaltyRecipients`, `addSellersToDisputeResolverAllowList`, `createBuyer`, `createDisputeResolver`, `createNewCollection`, `createSeller`, `createSellerAndOffer`, `getBuyerById`, `getBuyers`, `getDisputeResolverById`, `getDisputeResolverIdFromLogs`, `getDisputeResolvers`, `getOfferCollections`, `getPendingSellerUpdateFromLogs`, `getRoyaltyRecipients`, `getSellerByAdmin`, `getSellerByAssistant`, `getSellerByAuthToken`, `getSellerById`, `getSellers`, `getSellersByAddress`, `getSellersByTreasury`, `optInToDisputeResolverUpdate`, `optInToSellerUpdate`, `removeFeesFromDisputeResolver`, `removeRoyaltyRecipients`, `removeSellersFromDisputeResolverAllowList`, `searchSellerFromAuthToken`, `updateDisputeResolver`, `updateRoyaltyRecipients`, `updateSeller`, `updateSellerAndOptIn`

## Signatures

### `addFeesToDisputeResolver` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async addFeesToDisputeResolver(
    disputeResolverId: BigNumberish,
    fees: accounts.DisputeResolutionFee[],
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async addFeesToDisputeResolver(
    disputeResolverId: BigNumberish,
    fees: accounts.DisputeResolutionFee[],
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async addFeesToDisputeResolver(
    disputeResolverId: BigNumberish,
    fees: accounts.DisputeResolutionFee[],
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `addRoyaltyRecipients` (3 signatures)

```ts
public async addRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async addRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async addRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `addSellersToDisputeResolverAllowList` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async addSellersToDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: BigNumberish[],
    overrides: Partial<{
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async addSellersToDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: BigNumberish[],
    overrides?: Partial<{
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async addSellersToDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: BigNumberish[],
    overrides: Partial<{
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createBuyer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createBuyer(
    buyerToCreate: accounts.CreateBuyerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createBuyer(
    buyerToCreate: accounts.CreateBuyerArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createBuyer(
    buyerToCreate: accounts.CreateBuyerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createDisputeResolver` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createDisputeResolver(
    disputeResolverToCreate: accounts.CreateDisputeResolverArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createDisputeResolver(
    disputeResolverToCreate: accounts.CreateDisputeResolverArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createDisputeResolver(
    disputeResolverToCreate: accounts.CreateDisputeResolverArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createNewCollection` (3 signatures)

```ts
public async createNewCollection(
    collectionToCreate: accounts.CreateCollectionArgs,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createNewCollection(
    collectionToCreate: accounts.CreateCollectionArgs,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createNewCollection(
    collectionToCreate: accounts.CreateCollectionArgs,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createSeller` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createSeller(
    sellerToCreate: accounts.CreateSellerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createSeller(
    sellerToCreate: accounts.CreateSellerArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createSeller(
    sellerToCreate: accounts.CreateSellerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createSellerAndOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createSellerAndOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createSellerAndOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createSellerAndOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getBuyerById` (1 signature)

Returns buyer entity from subgraph.

```ts
public async getBuyerById(
    buyerId: BigNumberish,
    queryVars?: accounts.subgraph.SingleBuyerQueryVariables
  ): Promise<subgraph.BuyerFieldsFragment>
```

### `getBuyers` (1 signature)

Returns buyer entities from subgraph.

```ts
public async getBuyers(
    queryVars?: subgraph.GetBuyersQueryQueryVariables
  ): Promise<subgraph.BuyerFieldsFragment[]>
```

### `getDisputeResolverById` (1 signature)

Returns dispute resolver entity from subgraph.

```ts
public async getDisputeResolverById(
    disputeResolverId: BigNumberish,
    queryVars?: accounts.subgraph.SingleDisputeResolverQueryVariables
  ): Promise<subgraph.DisputeResolverFieldsFragment>
```

### `getDisputeResolverIdFromLogs` (1 signature)

Utility method to retrieve the created `exchangeId` from logs after calling `commitToOffer`.

```ts
public getDisputeResolverIdFromLogs(logs: Log[]): string | null {
    return getValueFromLogs({
      iface: accounts.iface.bosonAccountHandlerIface,
      logs,
      eventArgsKey: "disputeResolverId",
      eventName: "DisputeResolverCreated"
    })
```

### `getDisputeResolvers` (1 signature)

Returns dispute resolver entities from subgraph.

```ts
public async getDisputeResolvers(
    queryVars?: subgraph.GetDisputeResolversQueryQueryVariables
  ): Promise<subgraph.DisputeResolverFieldsFragment[]>
```

### `getOfferCollections` (1 signature)

```ts
public async getOfferCollections(
    queryVars?: subgraph.GetOfferCollectionsQueryQueryVariables
  ): Promise<subgraph.OfferCollectionFieldsFragment[]>
```

### `getPendingSellerUpdateFromLogs` (1 signature)

Utility method to retrieve the pending seller update fields from logs after calling `updateSeller`.

```ts
public getPendingSellerUpdateFromLogs(logs: Log[]): {
    sellerId: bigint
```

### `getRoyaltyRecipients` (1 signature)

```ts
public async getRoyaltyRecipients(
    sellerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  )
```

### `getSellerByAdmin` (1 signature)

Returns seller entity from subgraph.

```ts
public async getSellerByAdmin(
    admin: string,
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment>
```

### `getSellerByAssistant` (1 signature)

Returns seller entity from subgraph.

```ts
public async getSellerByAssistant(
    assistant: string,
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment>
```

### `getSellerByAuthToken` (1 signature)

Returns seller entity from subgraph that owns the given auth token (if any).

```ts
public async getSellerByAuthToken(
    tokenId: string,
    tokenType: number,
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment>
```

### `getSellerById` (1 signature)

Returns seller entity from subgraph.

```ts
public async getSellerById(
    sellerId: BigNumberish,
    queryVars?: accounts.subgraph.SingleSellerQueryVariables
  ): Promise<subgraph.SellerFieldsFragment>
```

### `getSellers` (1 signature)

Returns seller entities from subgraph.

```ts
public async getSellers(
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment[]>
```

### `getSellersByAddress` (1 signature)

Returns seller entity from subgraph. Matches `assistant`, `clerk`, `admin` or `treasury`.

```ts
public async getSellersByAddress(
    address: string,
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment[]>
```

### `getSellersByTreasury` (1 signature)

Returns seller entities from subgraph.

```ts
public async getSellersByTreasury(
    treasury: string,
    queryVars?: subgraph.GetSellersQueryQueryVariables
  ): Promise<subgraph.SellerFieldsFragment[]>
```

### `optInToDisputeResolverUpdate` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async optInToDisputeResolverUpdate(
    disputeResolverUpdates: accounts.OptInToDisputeResolverUpdateArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async optInToDisputeResolverUpdate(
    disputeResolverUpdates: accounts.OptInToDisputeResolverUpdateArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async optInToDisputeResolverUpdate(
    disputeResolverUpdates: accounts.OptInToDisputeResolverUpdateArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `optInToSellerUpdate` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async optInToSellerUpdate(
    sellerUpdates: accounts.OptInToSellerUpdateArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async optInToSellerUpdate(
    sellerUpdates: accounts.OptInToSellerUpdateArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async optInToSellerUpdate(
    sellerUpdates: accounts.OptInToSellerUpdateArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `removeFeesFromDisputeResolver` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async removeFeesFromDisputeResolver(
    disputeResolverId: BigNumberish,
    feeTokenAddresses: string[],
    overrides: Partial<{
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async removeFeesFromDisputeResolver(
    disputeResolverId: BigNumberish,
    feeTokenAddresses: string[],
    overrides?: Partial<{
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async removeFeesFromDisputeResolver(
    disputeResolverId: BigNumberish,
    feeTokenAddresses: string[],
    overrides: Partial<{
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `removeRoyaltyRecipients` (3 signatures)

```ts
public async removeRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async removeRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async removeRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `removeSellersFromDisputeResolverAllowList` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async removeSellersFromDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: string[],
    overrides: Partial<{
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async removeSellersFromDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: string[],
    overrides?: Partial<{
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async removeSellersFromDisputeResolverAllowList(
    disputeResolverId: BigNumberish,
    sellerAllowList: string[],
    overrides: Partial<{
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `searchSellerFromAuthToken` (1 signature)

Returns the seller id found in the subgraph, if any, based on an authTokenId owned by the specified address

```ts
public async searchSellerFromAuthToken(
    address: string,
    tokenType: number
  ): Promise<string>
```

### `updateDisputeResolver` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async updateDisputeResolver(
    disputeResolverId: BigNumberish,
    updates: accounts.DisputeResolverUpdates,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async updateDisputeResolver(
    disputeResolverId: BigNumberish,
    updates: accounts.DisputeResolverUpdates,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async updateDisputeResolver(
    disputeResolverId: BigNumberish,
    updates: accounts.DisputeResolverUpdates,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `updateRoyaltyRecipients` (3 signatures)

```ts
public async updateRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async updateRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async updateRoyaltyRecipients(
    sellerId: BigNumberish,
    royaltyRecipientIds: BigNumberish[],
    royaltyRecipients: accounts.RoyaltyRecipientInfo[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `updateSeller` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async updateSeller(
    sellerUpdates: accounts.UpdateSellerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async updateSeller(
    sellerUpdates: accounts.UpdateSellerArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async updateSeller(
    sellerUpdates: accounts.UpdateSellerArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `updateSellerAndOptIn` (1 signature)

Updates seller account by calling the `AccountHandlerFacet` contract, then optIn for all updates doable by the same account. Only callable by admin.

```ts
public async updateSellerAndOptIn(
    sellerUpdates: accounts.UpdateSellerArgs,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  ): Promise<TransactionResponse>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Adapters

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/adapters

> Wallet-library adapters that plug into the SDK.

# Adapters

The SDK is wallet-library-agnostic via `Web3LibAdapter`. Two implementations ship:

## `EthersAdapter` (ethers v5)

```ts twoslash
// @noErrors
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { ethers } from "ethers"

const provider = new ethers.providers.JsonRpcProvider(RPC_URL)
const wallet = new ethers.Wallet(PRIVATE_KEY, provider)
const adapter = new EthersAdapter(provider, wallet)  // (provider, signer?)
```

Constructor signature is `EthersAdapter(provider, signer?)`. The signer is optional for read-only adapters — pass any `Signer` (ethers `Wallet`, browser provider's `getSigner()`, KMS-backed signers) when you need to sign.

## viem bridge

```ts twoslash
// @noErrors
import { walletClientToWeb3LibAdapter } from "@bosonprotocol/x402b"
import { createWalletClient, http } from "viem"
import { polygon } from "viem/chains"
import { privateKeyToAccount } from "viem/accounts"

const wc = createWalletClient({
  account: privateKeyToAccount(PRIVATE_KEY),
  chain: polygon,
  transport: http(),
})

const adapter = walletClientToWeb3LibAdapter(wc)
```

## Implementing your own adapter

`Web3LibAdapter` requires methods to:
- Get signer address and chain.
- `signMessage`, `signTypedData`.
- `sendTransaction` and read receipts.
- Read on-chain (call, getLogs).

If you have a non-standard signer (HSM, MPC, custom RPC), implement this interface.

## Source

- Interface: [`@bosonprotocol/common/src/types/Web3LibAdapter.ts`](https://github.com/bosonprotocol/core-components/tree/main/packages/common/src/types)

---

# Reference — CoreSDK class

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/core-sdk

> The CoreSDK class — public surface, factory, and how the mixins compose.

# `CoreSDK`

The primary entry point of `@bosonprotocol/core-sdk`. Aggregates 13+ mixins into a single instance.

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"

const sdk = CoreSDK.fromDefaultConfig({
  web3Lib: new EthersAdapter(provider, signer),  // (provider, signer?)
  envName: "production",                         // required
  configId: "production-137-0",
})
```

## Constructors / factories

| Factory | Use when |
| --- | --- |
| `CoreSDK.fromDefaultConfig(opts)` | Standard. Pulls config from `@bosonprotocol/common`. Requires both `envName` and `configId`. |
| `new CoreSDK(opts)` | Custom config (testing, forks). |
| `getEnvConfigs(env)` (from `@bosonprotocol/common`) | List all known `configId` strings for an environment. |

## Options

```ts
{
  web3Lib: Web3LibAdapter,
  envName: EnvironmentType,           // "local" | "testing" | "staging" | "production"
  configId: string,                   // e.g. "production-137-0"
  metadataStorage?: MetadataStorage,  // for IPFS metadata
  theGraphStorage?: MetadataStorage,  // for The Graph IPFS gateway
  metaTx?: Partial<MetaTxConfig>,
}
```

## Mixins (methods groups)

| Mixin | Methods | Reference |
| --- | --- | --- |
| Accounts | `createSeller`, `createBuyer`, `createDisputeResolver`, `getSellersByAddress`, … | [→](./accounts) |
| Offers | `createOffer`, `voidOffer`, `getOffers`, `signFullOffer`, … | [→](./offers) |
| Exchanges | `commitToOffer`, `redeemVoucher`, `completeExchange`, `cancelVoucher`, `revokeVoucher`, `getExchanges`, … | [→](./exchanges) |
| Disputes | `raiseDispute`, `resolveDispute`, `escalateDispute`, `decideDispute`, `retractDispute`, … | [→](./disputes) |
| Funds | `depositFunds`, `withdrawFunds`, `getFunds`, … | [→](./funds) |
| MetaTx | `signMetaTxCommitToOffer`, `relayMetaTransaction`, … | [→](./meta-tx) |
| Orchestration | `createOfferAndCommit`, `signFullOffer`, … (no SDK helper currently wraps the buyer-side atomic commit+redeem — call `OrchestrationHandlerFacet` directly for that) | [→](./orchestration) |
| Groups | `createGroup`, `setGroupCondition`, `getGroups`, … | [→](./groups) |
| Marketplace | `searchOffers`, `getProductsWithVariants`, `facetOffers`, … | [→](./marketplace) |
| Search | full-text and filter helpers | [→](./search) |
| ERC20 / 721 / 1155 | `approve*`, `transfer*`, `balanceOf*` | [→](./erc-mixins) |

## Adapters

`Web3LibAdapter` is the pluggable interface. Implementations:
- `EthersAdapter` (ethers v5) — `@bosonprotocol/ethers-sdk`.
- viem bridge — `walletClientToWeb3LibAdapter()` in `@bosonprotocol/x402b`.

See [→ Adapters](./adapters).

:::info
This page is hand-authored today; the per-mixin pages will be generated from `mixin.ts` + `interface.ts` + `subgraph.ts` + `queries.graphql` per domain by the `scripts/docs-gen` pipeline.
:::

---

# Reference — Core SDK: Disputes

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/disputes

> Public methods on the Disputes mixin of @bosonprotocol/core-sdk.

# `Disputes` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `DisputesMixin`_

_Source: [`packages/core-sdk/src/disputes/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/disputes/mixin.ts)_



## Methods (13)

`decideDispute`, `escalateDispute`, `expireDispute`, `expireDisputeBatch`, `expireEscalatedDispute`, `extendDisputeTimeout`, `getDisputeById`, `getDisputes`, `raiseDispute`, `refuseEscalatedDispute`, `resolveDispute`, `retractDispute`, `signDisputeResolutionProposal`

## Signatures

### `decideDispute` (3 signatures)

Decides dispute by calling the `DisputeHandlerContract`.

```ts
public async decideDispute(
    exchangeId: BigNumberish,
    buyerPercent: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async decideDispute(
    exchangeId: BigNumberish,
    buyerPercent: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async decideDispute(
    exchangeId: BigNumberish,
    buyerPercent: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `escalateDispute` (3 signatures)

Escalates dispute by calling the `DisputeHandlerContract`.

```ts
public async escalateDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async escalateDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async escalateDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `expireDispute` (3 signatures)

Expires a dispute by calling the `DisputeHandlerContract`.

```ts
public async expireDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async expireDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async expireDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `expireDisputeBatch` (3 signatures)

Expires many disputes by calling the `DisputeHandlerContract`.

```ts
public async expireDisputeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async expireDisputeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async expireDisputeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `expireEscalatedDispute` (3 signatures)

Expires escalated dispute by calling the `DisputeHandlerContract`.

```ts
public async expireEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async expireEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async expireEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `extendDisputeTimeout` (3 signatures)

Extends the dispute timeout by calling the `DisputeHandlerContract`.

```ts
public async extendDisputeTimeout(
    exchangeId: BigNumberish,
    newDisputeTimeout: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async extendDisputeTimeout(
    exchangeId: BigNumberish,
    newDisputeTimeout: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async extendDisputeTimeout(
    exchangeId: BigNumberish,
    newDisputeTimeout: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getDisputeById` (1 signature)

Returns dispute entity from subgraph.

```ts
public async getDisputeById(
    disputeId: BigNumberish,
    queryVars?: SingleDisputeQueryVariables
  )
```

### `getDisputes` (1 signature)

Returns dispute entities from subgraph.

```ts
public async getDisputes(
    queryVars?: subgraph.GetDisputesQueryQueryVariables
  )
```

### `raiseDispute` (3 signatures)

Raises a dispute by calling the `DisputeHandlerContract`.

```ts
public async raiseDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async raiseDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async raiseDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `refuseEscalatedDispute` (3 signatures)

Refuses escalated dispute by calling the `DisputeHandlerContract`.

```ts
public async refuseEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async refuseEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async refuseEscalatedDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `resolveDispute` (3 signatures)

Resolves dispute by calling the `DisputeHandlerContract`. If caller is `buyer` then signature of `seller` is required as an argument. If caller if `seller` then vice-versa. The signature can be retrieved by calling the method `CoreSDK.signDisputeResolutionProposal`. - `args.exchangeId` - ID of disputed exchange. - `args.buyerPercent` - Percentage of deposit the buyer gets. - `args.sigR` - r signature value of counterparty. - `args.sigS` - s signature value of counterparty. - `args.sigV` - v signature value of counterparty.

```ts
public async resolveDispute(
    args:
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          sigR: BytesLike;
          sigS: BytesLike;
          sigV: BigNumberish;
          returnTxInfo: true;
        }
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          signature: string;
          returnTxInfo: true;
        }
  ): Promise<TransactionRequest>

public async resolveDispute(
    args:
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          sigR: BytesLike;
          sigS: BytesLike;
          sigV: BigNumberish;
          returnTxInfo?: false | undefined;
        }
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          signature: string;
          returnTxInfo?: false | undefined;
        }
  ): Promise<TransactionResponse>

public async resolveDispute(
    args:
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          sigR: BytesLike;
          sigS: BytesLike;
          sigV: BigNumberish;
          returnTxInfo?: boolean;
        }
      | {
          exchangeId: BigNumberish;
          buyerPercentBasisPoints: BigNumberish;
          signature: string;
          returnTxInfo?: boolean;
        }
  ): Promise<TransactionResponse | TransactionRequest>
```

### `retractDispute` (3 signatures)

Retracts a dispute by calling the `DisputeHandlerContract`.

```ts
public async retractDispute(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async retractDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async retractDispute(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `signDisputeResolutionProposal` (3 signatures)

Signs dispute resolution message. - `args.exchangeId` - ID of disputed exchange. - `args.buyerPercentBasisPoints` - Percentage of deposit the buyer gets.

```ts
public async signDisputeResolutionProposal(args: {
    exchangeId: BigNumberish;
    buyerPercentBasisPoints: BigNumberish;
    returnTypedDataToSign: true;
  }): Promise<StructuredData>

public async signDisputeResolutionProposal(args: {
    exchangeId: BigNumberish;
    buyerPercentBasisPoints: BigNumberish;
    returnTypedDataToSign?: false;
  }): Promise<ReturnType<typeof getSignatureParameters>>

public async signDisputeResolutionProposal(args: {
    exchangeId: BigNumberish;
    buyerPercentBasisPoints: BigNumberish;
    returnTypedDataToSign?: boolean;
  }): Promise<StructuredData | ReturnType<typeof getSignatureParameters>>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: ERC20 / 721 / 1155 mixins

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/erc-mixins

> Token helper mixins (erc1155, erc165, erc20, erc721) on @bosonprotocol/core-sdk.

# ERC20 / 721 / 1155 mixins

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

These mixins wrap the standard ERC token interfaces. They're used internally for approvals and balance reads and exposed for application code.

## `erc1155`

_Class: `ERC1155Mixin`_

_Source: [`packages/core-sdk/src/erc1155/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/erc1155/mixin.ts)_



## Methods (4)

`erc1155BalanceOf`, `erc1155Name`, `erc1155Symbol`, `erc1155Uri`

## Signatures

### `erc1155BalanceOf` (1 signature)

```ts
public async erc1155BalanceOf(
    args: Omit<Parameters<typeof balanceOf>[0], "web3Lib">
  ): Promise<ReturnType<typeof balanceOf>>
```

### `erc1155Name` (1 signature)

```ts
public async erc1155Name(
    args: Omit<Parameters<typeof name>[0], "web3Lib">
  ): Promise<ReturnType<typeof name>>
```

### `erc1155Symbol` (1 signature)

```ts
public async erc1155Symbol(
    args: Omit<Parameters<typeof symbol>[0], "web3Lib">
  ): Promise<ReturnType<typeof symbol>>
```

### `erc1155Uri` (1 signature)

```ts
public async erc1155Uri(
    args: Omit<Parameters<typeof uri>[0], "web3Lib">
  ): Promise<ReturnType<typeof uri>>
```

## `erc165`

_Class: `ERC165Mixin`_

_Source: [`packages/core-sdk/src/erc165/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/erc165/mixin.ts)_



## Methods (1)

`erc165SupportsInterface`

## Signatures

### `erc165SupportsInterface` (1 signature)

```ts
public async erc165SupportsInterface(
    args: Omit<Parameters<typeof supportsInterface>[0], "web3Lib">
  ): Promise<ReturnType<typeof supportsInterface>>
```

## `erc20`

_Class: `ERC20Mixin`_

_Source: [`packages/core-sdk/src/erc20/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/erc20/mixin.ts)_



## Methods (10)

`erc20Approve`, `erc20BalanceOf`, `erc20EnsureAllowance`, `erc20GetAllowance`, `erc20GetDecimals`, `erc20GetName`, `erc20GetSymbol`, `signReceiveWithErc2612Permit`, `signReceiveWithErc3009Authorization`, `signReceiveWithPermit2`

## Signatures

### `erc20Approve` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async erc20Approve(
    args: Omit<
      Parameters<typeof approve>[0],
      "web3Lib" | "theGraphStorage" | "metadataStorage"
    >,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async erc20Approve(
    args: Omit<
      Parameters<typeof approve>[0],
      "web3Lib" | "theGraphStorage" | "metadataStorage"
    >,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async erc20Approve(
    args: Omit<
      Parameters<typeof approve>[0],
      "web3Lib" | "theGraphStorage" | "metadataStorage"
    >,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `erc20BalanceOf` (1 signature)

```ts
public async erc20BalanceOf(
    args: Omit<Parameters<typeof balanceOf>[0], "web3Lib">
  ): Promise<ReturnType<typeof balanceOf>>
```

### `erc20EnsureAllowance` (1 signature)

```ts
public async erc20EnsureAllowance(
    args: Omit<Parameters<typeof ensureAllowance>[0], "web3Lib">
  ): Promise<ReturnType<typeof ensureAllowance>>
```

### `erc20GetAllowance` (1 signature)

```ts
public async erc20GetAllowance(
    args: Omit<Parameters<typeof getAllowance>[0], "web3Lib">
  ): Promise<ReturnType<typeof getAllowance>>
```

### `erc20GetDecimals` (1 signature)

```ts
public async erc20GetDecimals(
    args: Omit<Parameters<typeof getDecimals>[0], "web3Lib">
  ): Promise<ReturnType<typeof getDecimals>>
```

### `erc20GetName` (1 signature)

```ts
public async erc20GetName(
    args: Omit<Parameters<typeof getName>[0], "web3Lib">
  ): Promise<ReturnType<typeof getName>>
```

### `erc20GetSymbol` (1 signature)

```ts
public async erc20GetSymbol(
    args: Omit<Parameters<typeof getSymbol>[0], "web3Lib">
  ): Promise<ReturnType<typeof getSymbol>>
```

### `signReceiveWithErc2612Permit` (3 signatures)

Overload: returnTypedDataToSign is true → returns StructuredData

```ts
public async signReceiveWithErc2612Permit(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    deadline: BigNumberish,
    overrides: Partial<{ spender: string }> & { returnTypedDataToSign: true }
  ): Promise<StructuredData>

public async signReceiveWithErc2612Permit(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    deadline: BigNumberish,
    overrides?: Partial<{ spender: string; returnTypedDataToSign?: false }>
  ): Promise<TransferAuthorization & { strategy: "EIP2612" }>

public async signReceiveWithErc2612Permit(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    deadline: BigNumberish,
    overrides: Partial<{
      spender: string;
      returnTypedDataToSign: boolean;
    }> = {}
  ): Promise<
    (TransferAuthorization & { strategy: "EIP2612" }) | StructuredData
  >
```

### `signReceiveWithErc3009Authorization` (3 signatures)

Overload: returnTypedDataToSign is true → returns StructuredData

```ts
public async signReceiveWithErc3009Authorization(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    validAfter: BigNumberish,
    validBefore: BigNumberish,
    overrides: Partial<{ spender: string }> & { returnTypedDataToSign: true }
  ): Promise<StructuredData>

public async signReceiveWithErc3009Authorization(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    validAfter: BigNumberish,
    validBefore: BigNumberish,
    overrides?: Partial<{ spender: string; returnTypedDataToSign?: false }>
  ): Promise<TransferAuthorization & { strategy: "ERC3009" }>

public async signReceiveWithErc3009Authorization(
    exchangeToken: string,
    tokenDomain: { name: string; version: string },
    value: BigNumberish,
    validAfter: BigNumberish,
    validBefore: BigNumberish,
    overrides: Partial<{
      spender: string;
      returnTypedDataToSign: boolean;
    }> = {}
  ): Promise<
    (TransferAuthorization & { strategy: "ERC3009" }) | StructuredData
  >
```

### `signReceiveWithPermit2` (3 signatures)

Overload: returnTypedDataToSign is true → returns StructuredData

```ts
public async signReceiveWithPermit2(
    exchangeToken: string,
    value: BigNumberish,
    deadline: BigNumberish,
    overrides: Partial<{
      spender: string;
      permit2Address: string;
      permit2Nonce: BigNumberish;
    }> & { returnTypedDataToSign: true }
  ): Promise<StructuredData>

public async signReceiveWithPermit2(
    exchangeToken: string,
    value: BigNumberish,
    deadline: BigNumberish,
    overrides?: Partial<{
      spender: string;
      permit2Address: string;
      permit2Nonce: BigNumberish;
      returnTypedDataToSign?: false;
    }>
  ): Promise<TransferAuthorization & { strategy: "Permit2" }>

public async signReceiveWithPermit2(
    exchangeToken: string,
    value: BigNumberish,
    deadline: BigNumberish,
    overrides: Partial<{
      spender: string;
      permit2Address: string;
      permit2Nonce: BigNumberish;
      returnTypedDataToSign: boolean;
    }> = {}
  ): Promise<
    (TransferAuthorization & { strategy: "Permit2" }) | StructuredData
  >
```

## `erc721`

_Class: `ERC721Mixin`_

_Source: [`packages/core-sdk/src/erc721/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/erc721/mixin.ts)_



## Methods (6)

`erc721BalanceOf`, `erc721Name`, `erc721OwnerOf`, `erc721Symbol`, `erc721TokenOfOwnerByIndex`, `erc721TokenUri`

## Signatures

### `erc721BalanceOf` (1 signature)

```ts
public async erc721BalanceOf(
    args: Omit<Parameters<typeof balanceOf>[0], "web3Lib">
  ): Promise<ReturnType<typeof balanceOf>>
```

### `erc721Name` (1 signature)

```ts
public async erc721Name(
    args: Omit<Parameters<typeof name>[0], "web3Lib">
  ): Promise<ReturnType<typeof name>>
```

### `erc721OwnerOf` (1 signature)

```ts
public async erc721OwnerOf(
    args: Omit<Parameters<typeof ownerOf>[0], "web3Lib">
  ): Promise<ReturnType<typeof ownerOf>>
```

### `erc721Symbol` (1 signature)

```ts
public async erc721Symbol(
    args: Omit<Parameters<typeof symbol>[0], "web3Lib">
  ): Promise<ReturnType<typeof symbol>>
```

### `erc721TokenOfOwnerByIndex` (1 signature)

```ts
public async erc721TokenOfOwnerByIndex(
    args: Omit<Parameters<typeof tokenOfOwnerByIndex>[0], "web3Lib">
  ): Promise<ReturnType<typeof tokenOfOwnerByIndex>>
```

### `erc721TokenUri` (1 signature)

```ts
public async erc721TokenUri(
    args: Omit<Parameters<typeof tokenUri>[0], "web3Lib">
  ): Promise<ReturnType<typeof tokenUri>>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Build → Marketplace operators → Token-gated launches](/build/marketplace/token-gated).
- [Recipes → ERC-20 approve + commit](/recipes/erc20-commit).

---

# Reference — Core SDK: Errors

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/errors-mixin

> Public methods on the Errors mixin of @bosonprotocol/core-sdk.

# `Errors` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `ErrorMixin`_

_Source: [`packages/core-sdk/src/errors/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/errors/mixin.ts)_



## Methods (1)

`parseError`

## Signatures

### `parseError` (1 signature)

```ts
public parseError(error: object): object {
    return { ...error, decoded: this.recurseParseError(error) }
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Event logs

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/event-logs

> Public methods on the Event logs mixin of @bosonprotocol/core-sdk.

# `Event logs` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `EventLogsMixin`_

_Source: [`packages/core-sdk/src/event-logs/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/event-logs/mixin.ts)_



## Methods (2)

`getConditionalCommitAuthorizedEventLogs`, `getEventLogs`

## Signatures

### `getConditionalCommitAuthorizedEventLogs` (1 signature)

Returns conditionalCommitAuthorized event logs from subgraph.

```ts
public async getConditionalCommitAuthorizedEventLogs(
    queryVars?: subgraph.GetConditionalCommitAuthorizedEventLogsQueryQueryVariables
  )
```

### `getEventLogs` (1 signature)

Returns event logs from subgraph.

```ts
public async getEventLogs(
    queryVars?: subgraph.GetEventLogsQueryQueryVariables
  )
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Exchanges

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/exchanges

> Public methods on the Exchanges mixin of @bosonprotocol/core-sdk.

# `Exchanges` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `ExchangesMixin`_

_Source: [`packages/core-sdk/src/exchanges/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/exchanges/mixin.ts)_



## Methods (16)

`cancelVoucher`, `commitToBuyerOffer`, `commitToConditionalOffer`, `commitToOffer`, `completeExchange`, `completeExchangeBatch`, `createOfferAndCommit`, `expireVoucher`, `getCommittedExchangeIdFromLogs`, `getExchangeById`, `getExchanges`, `getExchangeTokenId`, `parseTokenId`, `redeemVoucher`, `revokeVoucher`, `signFullOffer`

## Signatures

### `cancelVoucher` (3 signatures)

Cancels an existing voucher by calling the `ExchangeHandlerContract`. Callable by buyer.

```ts
public async cancelVoucher(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async cancelVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async cancelVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `commitToBuyerOffer` (3 signatures)

Commits to a buyer initiated offer by calling the `ExchangeCommitFacet`. This transaction only succeeds if the buyer has deposited enough funds to lock the offer's price.

```ts
public async commitToBuyerOffer(
    offerId: BigNumberish,
    sellerParams: SellerOfferArgs,
    overrides: Partial<{
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToBuyerOffer(
    offerId: BigNumberish,
    sellerParams?: SellerOfferArgs,
    overrides?: Partial<{
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async commitToBuyerOffer(
    offerId: BigNumberish,
    sellerParams: SellerOfferArgs = {},
    overrides: Partial<{
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `commitToConditionalOffer` (3 signatures)

Commits to a conditional offer by calling the `ExchangeHandlerContract`. This transaction only succeeds if the seller has deposited funds.

```ts
public async commitToConditionalOffer(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      buyer: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToConditionalOffer(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides?: Partial<{
      buyer: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async commitToConditionalOffer(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      buyer: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `commitToOffer` (3 signatures)

Commits to a seller initiated offer by calling the `ExchangeCommitFacet`. This transaction only succeeds if the seller has deposited enough funds to lock the offer's sellerDeposit.

```ts
public async commitToOffer(
    offerId: BigNumberish,
    overrides: Partial<{
      buyer: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToOffer(
    offerId: BigNumberish,
    overrides?: Partial<{
      buyer: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async commitToOffer(
    offerId: BigNumberish,
    overrides: Partial<{
      buyer: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `completeExchange` (3 signatures)

Completes an existing voucher by calling the `ExchangeHandlerContract`. Callable by buyer or seller assistant.

```ts
public async completeExchange(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async completeExchange(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async completeExchange(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `completeExchangeBatch` (3 signatures)

Completes a batch of existing vouchers by calling the `ExchangeHandlerContract`. Callable by buyer or seller assistant.

```ts
public async completeExchangeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async completeExchangeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async completeExchangeBatch(
    exchangeIds: BigNumberish[],
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createOfferAndCommit` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createOfferAndCommit(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createOfferAndCommit(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createOfferAndCommit(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `expireVoucher` (3 signatures)

Expires an existing voucher by calling the `ExchangeHandlerContract`.

```ts
public async expireVoucher(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async expireVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async expireVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getCommittedExchangeIdFromLogs` (1 signature)

Utility method to retrieve the created `exchangeId` from logs after calling `commitToOffer` or `commitToBuyerOffer`.

```ts
public getCommittedExchangeIdFromLogs(logs: Log[]): string | null {
    return (
      getValueFromLogs({
        iface: bosonExchangeHandlerIface,
        logs,
        eventArgsKey: "exchangeId",
        eventName: "BuyerCommitted"
      }) ||
      getValueFromLogs({
        iface: bosonExchangeHandlerIface,
        logs,
        eventArgsKey: "exchangeId",
        eventName: "SellerCommitted"
      })
    )
```

### `getExchangeById` (1 signature)

Returns exchange entity from subgraph.

```ts
public async getExchangeById(
    exchangeId: BigNumberish,
    queryVars?: subgraph.GetExchangeByIdQueryQueryVariables
  ): Promise<subgraph.ExchangeFieldsFragment>
```

### `getExchanges` (1 signature)

Returns exchange entities from subgraph.

```ts
public async getExchanges(
    queryVars?: subgraph.GetExchangesQueryQueryVariables
  ): Promise<subgraph.ExchangeFieldsFragment[]>
```

### `getExchangeTokenId` (1 signature)

```ts
public getExchangeTokenId(
    exchangeId: BigNumberish,
    offerId: BigNumberish
  ): BigNumber
```

### `parseTokenId` (1 signature)

```ts
public parseTokenId(tokenId: BigNumberish): {
    offerId: BigNumber
```

### `redeemVoucher` (3 signatures)

Redeems an existing voucher by calling the `ExchangeHandlerContract`. Callable by buyer.

```ts
public async redeemVoucher(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async redeemVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async redeemVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `revokeVoucher` (3 signatures)

Revokes an existing voucher by calling the `ExchangeHandlerContract`. Callable by seller `assistant`.

```ts
public async revokeVoucher(
    exchangeId: BigNumberish,
    returnTxInfo: true
  ): Promise<TransactionRequest>

public async revokeVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: false | undefined
  ): Promise<TransactionResponse>

public async revokeVoucher(
    exchangeId: BigNumberish,
    returnTxInfo?: boolean
  ): Promise<TransactionResponse | TransactionRequest>
```

### `signFullOffer` (3 signatures)

```ts
public async signFullOffer(args: {
    fullOfferArgsUnsigned: Omit<FullOfferArgs, "signature">;
    returnTypedDataToSign: true;
  }): Promise<StructuredData>

public async signFullOffer(args: {
    fullOfferArgsUnsigned: Omit<FullOfferArgs, "signature">;
    returnTypedDataToSign?: false;
  }): Promise<ReturnType<typeof getSignatureParameters>>

public async signFullOffer(args: {
    fullOfferArgsUnsigned: Omit<FullOfferArgs, "signature">;
    returnTypedDataToSign?: boolean;
  }): Promise<StructuredData | ReturnType<typeof getSignatureParameters>>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Funds

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/funds

> Public methods on the Funds mixin of @bosonprotocol/core-sdk.

# `Funds` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `FundsMixin`_

_Source: [`packages/core-sdk/src/funds/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/funds/mixin.ts)_



## Methods (5)

`depositFunds`, `getFunds`, `getFundsById`, `withdrawAllAvailableFunds`, `withdrawFunds`

## Signatures

### `depositFunds` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async depositFunds(
    entityId: BigNumberish,
    fundsAmount: BigNumberish,
    fundsTokenAddress: string,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async depositFunds(
    entityId: BigNumberish,
    fundsAmount: BigNumberish,
    fundsTokenAddress?: string,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async depositFunds(
    entityId: BigNumberish,
    fundsAmount: BigNumberish,
    fundsTokenAddress: string = AddressZero,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getFunds` (1 signature)

Returns funds entities from subgraph.

```ts
public async getFunds(
    queryVars?: subgraph.GetFundsQueryVariables
  ): Promise<subgraph.FundsEntityFieldsFragment[]>
```

### `getFundsById` (1 signature)

Returns funds entity from subgraph.

```ts
public async getFundsById(
    fundsId: BigNumberish,
    queryVars?: subgraph.GetFundsByIdQueryVariables
  ): Promise<subgraph.FundsEntityFieldsFragment>
```

### `withdrawAllAvailableFunds` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async withdrawAllAvailableFunds(
    entityId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async withdrawAllAvailableFunds(
    entityId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async withdrawAllAvailableFunds(
    entityId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `withdrawFunds` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async withdrawFunds(
    entityId: BigNumberish,
    tokensToWithdraw: Array<string>,
    amountsToWithdraw: Array<BigNumberish>,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async withdrawFunds(
    entityId: BigNumberish,
    tokensToWithdraw: Array<string>,
    amountsToWithdraw: Array<BigNumberish>,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async withdrawFunds(
    entityId: BigNumberish,
    tokensToWithdraw: Array<string>,
    amountsToWithdraw: Array<BigNumberish>,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Groups

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/groups

> Public methods on the Groups mixin of @bosonprotocol/core-sdk.

# `Groups` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `GroupsMixin`_

_Source: [`packages/core-sdk/src/groups/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/groups/mixin.ts)_



## Methods (1)

`createGroup`

## Signatures

### `createGroup` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createGroup(
    groupToCreate: CreateGroupArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createGroup(
    groupToCreate: CreateGroupArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createGroup(
    groupToCreate: CreateGroupArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Marketplaces

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/marketplace

> Public methods on the Marketplaces mixin of @bosonprotocol/core-sdk.

# `Marketplaces` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `MarketplaceMixin`_

_Source: [`packages/core-sdk/src/marketplaces/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/marketplaces/mixin.ts)_



## Methods (1)

`marketplace`

## Signatures

### `marketplace` (1 signature)

```ts
public marketplace<T extends keyof MarketplaceTypeToClass>(
    type: T,
    handler: T extends MarketplaceType.OPENSEA
      ? OpenSeaSDKHandler
      : MarketplaceHandler,
    feeRecipient: string
  ): MarketplaceTypeToClass[T]
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: MetaTx

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/meta-tx

> Public methods on the MetaTx mixin of @bosonprotocol/core-sdk.

# `MetaTx` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `MetaTxMixin`_

_Source: [`packages/core-sdk/src/meta-tx/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/meta-tx/mixin.ts)_



## Methods (42)

`executeMetaTransaction`, `getResubmittedMetaTx`, `relayBiconomyMetaTransaction`, `relayMetaTransaction`, `signMetaTx`, `signMetaTxCallExternalContract`, `signMetaTxCancelVoucher`, `signMetaTxCommitToBuyerOffer`, `signMetaTxCommitToConditionalOffer`, `signMetaTxCommitToConditionalOfferAndRedeemVoucher`, `signMetaTxCommitToOffer`, `signMetaTxCommitToOfferAndRedeemVoucher`, `signMetaTxCompleteExchange`, `signMetaTxCompleteExchangeBatch`, `signMetaTxCreateGroup`, `signMetaTxCreateOffer`, `signMetaTxCreateOfferAndCommit`, `signMetaTxCreateOfferBatch`, `signMetaTxCreateOfferCommitAndRedeem`, `signMetaTxCreateOfferWithCondition`, `signMetaTxCreateSeller`, `signMetaTxDepositFunds`, `signMetaTxEscalateDispute`, `signMetaTxExpireVoucher`, `signMetaTxExtendDisputeTimeout`, `signMetaTxExtendOffer`, `signMetaTxExtendOfferBatch`, `signMetaTxOptInToSellerUpdate`, `signMetaTxPreMint`, `signMetaTxRaiseDispute`, `signMetaTxRedeemVoucher`, `signMetaTxReserveRange`, `signMetaTxResolveDispute`, `signMetaTxRetractDispute`, `signMetaTxRevokeVoucher`, `signMetaTxSetApprovalForAll`, `signMetaTxSetApprovalForAllToContract`, `signMetaTxUpdateSeller`, `signMetaTxUpdateSellerAndOptIn`, `signMetaTxVoidOffer`, `signMetaTxVoidOfferBatch`, `signMetaTxWithdrawFunds`

## Signatures

### `executeMetaTransaction` (1 signature)

Execute a signed meta transaction directly on-chain (no Biconomy relayer). Routes to `executeMetaTransaction` or `executeMetaTransactionWithTokenTransferAuthorization` depending on whether `transferAuthorizations` is provided and non-empty. The wallet backing the SDK pays the gas; pass `overrides.userAddress` when the meta-tx signer differs from that wallet.

```ts
public async executeMetaTransaction(
    metaTxParams: {
      functionName: string;
      functionSignature: BytesLike;
      nonce: BigNumberish;
      sigR: BytesLike;
      sigS: BytesLike;
      sigV: BigNumberish;
      transferAuthorizations?: TransferAuthorization[];
    },
    overrides: Partial<{
      userAddress: string;
      contractAddress: string;
    }> = {}
  ): Promise<TransactionResponse>
```

### `getResubmittedMetaTx` (1 signature)

Returns information of submitted meta transaction. See https://docs.biconomy.io/api/native-meta-tx/get-retried-hashes.

```ts
public async getResubmittedMetaTx(
    originalMetaTxHash: string,
    overrides: Partial<{
      contractAddress: string;
      metaTxConfig: Partial<Omit<MetaTxConfig, "apiIds"> & { apiId: string }>;
      metaTransactionMethod: string;
    }> = {}
  ): Promise<GetRetriedHashesData>
```

### `relayBiconomyMetaTransaction` (1 signature)

```ts
public async relayBiconomyMetaTransaction(
    contractAddress: string,
    metaTxParams: {
      request: Parameters<
        (typeof handler)["relayBiconomyMetaTransaction"]
      >[0]["metaTx"]["params"]["request"];
      domainSeparator: Parameters<
        (typeof handler)["relayBiconomyMetaTransaction"]
      >[0]["metaTx"]["params"]["domainSeparator"];
      signature: Parameters<
        (typeof handler)["relayBiconomyMetaTransaction"]
      >[0]["metaTx"]["params"]["signature"];
    },
    overrides: Partial<{
      userAddress: string;
      metaTxConfig: Partial<
        Omit<MetaTxConfig, "apiIds" | "forwarderAbi"> & { apiId: string }
      >;
      metaTransactionMethod: string;
    }> = {}
  ): Promise<TransactionResponse>
```

### `relayMetaTransaction` (1 signature)

Relay a meta transaction,

```ts
public async relayMetaTransaction(
    metaTxParams: {
      functionName: string;
      functionSignature: BytesLike;
      nonce: BigNumberish;
      sigR: BytesLike;
      sigS: BytesLike;
      sigV: BigNumberish;
      transferAuthorizations?: TransferAuthorization[];
    },
    overrides: Partial<{
      userAddress: string;
      contractAddress: string;
      metaTxConfig: Partial<Omit<MetaTxConfig, "apiIds"> & { apiId: string }>;
      metaTransactionMethod: string;
    }> = {}
  ): Promise<TransactionResponse>
```

### `signMetaTx` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTx(
    args: Omit<
      Parameters<typeof handler.signMetaTx>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTx(
    args: Omit<
      Parameters<typeof handler.signMetaTx>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTx(
    args: Omit<
      Parameters<typeof handler.signMetaTx>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCallExternalContract` (1 signature)

```ts
public async signMetaTxCallExternalContract(
    args: Omit<
      Parameters<typeof handler.signMetaTxCallExternalContract>[0],
      | "web3Lib"
      | "bosonVoucherAddress"
      | "chainId"
      | "nonce"
      | "forwarderAddress"
      | "batchId"
      | "forwarderAbi"
      | "relayerUrl"
    >,
    overrides: Partial<{
      batchId?: BigNumberish;
      txGas?: number;
    }> = {}
  )
```

### `signMetaTxCancelVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCancelVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCancelVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCancelVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCancelVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCancelVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCancelVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCommitToBuyerOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCommitToBuyerOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToBuyerOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCommitToBuyerOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToBuyerOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCommitToBuyerOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToBuyerOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCommitToConditionalOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCommitToConditionalOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToConditionalOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCommitToConditionalOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToConditionalOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCommitToConditionalOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToConditionalOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCommitToConditionalOfferAndRedeemVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCommitToConditionalOfferAndRedeemVoucher(
    args: Omit<
      Parameters<
        typeof handler.signMetaTxCommitToConditionalOfferAndRedeemVoucher
      >[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCommitToConditionalOfferAndRedeemVoucher(
    args: Omit<
      Parameters<
        typeof handler.signMetaTxCommitToConditionalOfferAndRedeemVoucher
      >[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCommitToConditionalOfferAndRedeemVoucher(
    args: Omit<
      Parameters<
        typeof handler.signMetaTxCommitToConditionalOfferAndRedeemVoucher
      >[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCommitToOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCommitToOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCommitToOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCommitToOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCommitToOfferAndRedeemVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCommitToOfferAndRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOfferAndRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCommitToOfferAndRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOfferAndRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCommitToOfferAndRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxCommitToOfferAndRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCompleteExchange` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCompleteExchange(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCompleteExchange(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCompleteExchange(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCompleteExchangeBatch` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCompleteExchangeBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchangeBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCompleteExchangeBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchangeBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCompleteExchangeBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCompleteExchangeBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateGroup` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateGroup(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateGroup>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateGroup(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateGroup>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateGroup(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateGroup>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateOfferAndCommit` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateOfferAndCommit(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferAndCommit>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateOfferAndCommit(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferAndCommit>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateOfferAndCommit(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferAndCommit>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateOfferBatch` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateOfferCommitAndRedeem` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateOfferCommitAndRedeem(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferCommitAndRedeem>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateOfferCommitAndRedeem(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferCommitAndRedeem>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateOfferCommitAndRedeem(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferCommitAndRedeem>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateOfferWithCondition` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateOfferWithCondition(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferWithCondition>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateOfferWithCondition(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferWithCondition>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateOfferWithCondition(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateOfferWithCondition>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxCreateSeller` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxCreateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxCreateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxCreateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxCreateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxDepositFunds` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxDepositFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxDepositFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxDepositFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxDepositFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxDepositFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxDepositFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxEscalateDispute` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxEscalateDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxEscalateDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxEscalateDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxEscalateDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxEscalateDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxEscalateDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxExpireVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxExpireVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxExpireVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxExpireVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxExpireVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxExpireVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxExpireVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxExtendDisputeTimeout` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxExtendDisputeTimeout(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendDisputeTimeout>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxExtendDisputeTimeout(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendDisputeTimeout>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxExtendDisputeTimeout(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendDisputeTimeout>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxExtendOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxExtendOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxExtendOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxExtendOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxExtendOfferBatch` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxExtendOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxExtendOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxExtendOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxExtendOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxOptInToSellerUpdate` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxOptInToSellerUpdate(
    args: Omit<
      Parameters<typeof handler.signMetaTxOptInToSellerUpdate>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxOptInToSellerUpdate(
    args: Omit<
      Parameters<typeof handler.signMetaTxOptInToSellerUpdate>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxOptInToSellerUpdate(
    args: Omit<
      Parameters<typeof handler.signMetaTxOptInToSellerUpdate>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxPreMint` (1 signature)

```ts
public async signMetaTxPreMint(
    args: Omit<
      Parameters<typeof handler.signMetaTxPreMint>[0],
      | "web3Lib"
      | "bosonVoucherAddress"
      | "chainId"
      | "forwarderAddress"
      | "batchId"
      | "forwarderAbi"
      | "relayerUrl"
    >,
    overrides: Partial<{
      batchId: BigNumberish;
    }> = {}
  )
```

### `signMetaTxRaiseDispute` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxRaiseDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRaiseDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxRaiseDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRaiseDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxRaiseDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRaiseDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxRedeemVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxRedeemVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRedeemVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxReserveRange` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxReserveRange(
    args: Omit<
      Parameters<typeof handler.signMetaTxReserveRange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId" | "to"
    > & { to: "seller" | "contract"; returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxReserveRange(
    args: Omit<
      Parameters<typeof handler.signMetaTxReserveRange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId" | "to"
    > & { to: "seller" | "contract"; returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxReserveRange(
    args: Omit<
      Parameters<typeof handler.signMetaTxReserveRange>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId" | "to"
    > & { to: "seller" | "contract" }
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxResolveDispute` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxResolveDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxResolveDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxResolveDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxResolveDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxResolveDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxResolveDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxRetractDispute` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxRetractDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRetractDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxRetractDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRetractDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxRetractDispute(
    args: Omit<
      Parameters<typeof handler.signMetaTxRetractDispute>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxRevokeVoucher` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxRevokeVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRevokeVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxRevokeVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRevokeVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxRevokeVoucher(
    args: Omit<
      Parameters<typeof handler.signMetaTxRevokeVoucher>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxSetApprovalForAll` (1 signature)

```ts
public async signMetaTxSetApprovalForAll(
    args: Omit<
      Parameters<typeof handler.signMetaTxSetApprovalForAll>[0],
      | "web3Lib"
      | "bosonVoucherAddress"
      | "chainId"
      | "nonce"
      | "forwarderAddress"
      | "batchId"
      | "forwarderAbi"
      | "relayerUrl"
    >,
    overrides: Partial<{
      batchId: BigNumberish;
    }> = {}
  )
```

### `signMetaTxSetApprovalForAllToContract` (1 signature)

```ts
public async signMetaTxSetApprovalForAllToContract(
    args: Omit<
      Parameters<typeof handler.signMetaTxSetApprovalForAllToContract>[0],
      | "web3Lib"
      | "bosonVoucherAddress"
      | "chainId"
      | "nonce"
      | "forwarderAddress"
      | "batchId"
      | "forwarderAbi"
      | "relayerUrl"
    > & {
      bosonVoucherAddress?: string;
    },
    overrides: Partial<{
      batchId?: BigNumberish;
      txGas?: number;
    }> = {}
  )
```

### `signMetaTxUpdateSeller` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxUpdateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxUpdateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxUpdateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxUpdateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxUpdateSeller(
    args: Omit<
      Parameters<typeof handler.signMetaTxUpdateSeller>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxUpdateSellerAndOptIn` (1 signature)

```ts
public async signMetaTxUpdateSellerAndOptIn(
    sellerUpdates: accounts.UpdateSellerArgs
  ): Promise<TransactionResponse>
```

### `signMetaTxVoidOffer` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxVoidOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxVoidOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxVoidOffer(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOffer>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxVoidOfferBatch` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxVoidOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxVoidOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxVoidOfferBatch(
    args: Omit<
      Parameters<typeof handler.signMetaTxVoidOfferBatch>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

### `signMetaTxWithdrawFunds` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signMetaTxWithdrawFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxWithdrawFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signMetaTxWithdrawFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxWithdrawFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    > & { returnTypedDataToSign?: false | undefined }
  ): Promise<SignedMetaTx>

public async signMetaTxWithdrawFunds(
    args: Omit<
      Parameters<typeof handler.signMetaTxWithdrawFunds>[0],
      "web3Lib" | "metaTxHandlerAddress" | "chainId"
    >
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Metadata (mixin)

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/metadata-mixin

> Public methods on the Metadata (mixin) mixin of @bosonprotocol/core-sdk.

# `Metadata (mixin)` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `MetadataMixin`_

_Source: [`packages/core-sdk/src/metadata/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/metadata/mixin.ts)_



## Methods (10)

`getAllProductsWithNotVoidedVariants`, `getAllProductsWithVariants`, `getBaseMetadataEntities`, `getBundleMetadataEntities`, `getMetadata`, `getProductV1MetadataEntities`, `getProductV1Products`, `getProductWithVariants`, `getProductWithVariantsFromOfferId`, `storeMetadata`

## Signatures

### `getAllProductsWithNotVoidedVariants` (1 signature)

```ts
public async getAllProductsWithNotVoidedVariants(
    queryVars?: subgraph.GetAllProductsWithNotVoidedVariantsQueryQueryVariables
  ): Promise<
    subgraph.BaseProductV1ProductWithNotVoidedVariantsFieldsFragment[]
  >
```

### `getAllProductsWithVariants` (1 signature)

```ts
public getAllProductsWithVariants(
    queryVars?: subgraph.GetProductV1ProductsWithVariantsQueryQueryVariables
  ): Promise<subgraph.BaseProductV1ProductWithVariantsFieldsFragment[]>
```

### `getBaseMetadataEntities` (1 signature)

Returns `BASE` type offer metadata entities from subgraph.

```ts
public async getBaseMetadataEntities(
    queryVars?: subgraph.GetBaseMetadataEntitiesQueryQueryVariables
  ): Promise<subgraph.BaseMetadataEntityFieldsFragment[]>
```

### `getBundleMetadataEntities` (1 signature)

Returns `BUNDLE` type offer metadata entities from subgraph.

```ts
public async getBundleMetadataEntities(
    queryVars?: subgraph.GetBundleMetadataEntitiesQueryQueryVariables
  ): Promise<subgraph.BundleMetadataEntityFieldsFragment[]>
```

### `getMetadata` (1 signature)

Returns supported offer metadata from passed in `MetadataStorage` instance. storage instance.

```ts
public async getMetadata(
    metadataHashOrUri: string
  ): Promise<OfferOrSellerMetadata>
```

### `getProductV1MetadataEntities` (1 signature)

Returns `PRODUCT_V1` type offer metadata entities from subgraph.

```ts
public async getProductV1MetadataEntities(
    queryVars?: subgraph.GetProductV1MetadataEntitiesQueryQueryVariables
  ): Promise<subgraph.ProductV1MetadataEntityFieldsFragment[]>
```

### `getProductV1Products` (1 signature)

```ts
public async getProductV1Products(
    queryVars?: subgraph.GetProductV1ProductsQueryQueryVariables
  ): Promise<subgraph.BaseProductV1ProductFieldsFragment[]>
```

### `getProductWithVariants` (1 signature)

```ts
public async getProductWithVariants(
    sellerId: string,
    productUuid: string
  ): Promise<
```

### `getProductWithVariantsFromOfferId` (1 signature)

```ts
public getProductWithVariantsFromOfferId(
    offerId: string
  ): ReturnType<typeof getProductWithVariantsFromOfferId>
```

### `storeMetadata` (1 signature)

Stores supported offer metadata via the MetadataStorage instance which was passed in at construction.

```ts
public async storeMetadata(metadata: OfferOrSellerMetadata): Promise<string> {
    if (!this._metadataStorage)
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Native meta-tx

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/native-meta-tx

> Public methods on the Native meta-tx mixin of @bosonprotocol/core-sdk.

# `Native meta-tx` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `NativeMetaTxMixin`_

_Source: [`packages/core-sdk/src/native-meta-tx/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/native-meta-tx/mixin.ts)_



## Methods (3)

`executeNativeMetaTransaction`, `relayNativeMetaTransaction`, `signNativeMetaTxApproveExchangeToken`

## Signatures

### `executeNativeMetaTransaction` (1 signature)

Execute a signed native meta transaction directly on-chain (no Biconomy relayer). The wallet backing the SDK pays the gas; pass `overrides.userAddress` when the meta-tx signer differs from that wallet.

```ts
public async executeNativeMetaTransaction(
    contractAddress: string,
    metaTxParams: {
      functionSignature: BytesLike;
      sigR: BytesLike;
      sigS: BytesLike;
      sigV: BigNumberish;
    },
    overrides: Partial<{
      userAddress: string;
    }> = {}
  ): Promise<TransactionResponse>
```

### `relayNativeMetaTransaction` (1 signature)

Relay a native meta transaction,

```ts
public async relayNativeMetaTransaction(
    contractAddress: string,
    metaTxParams: {
      functionSignature: BytesLike;
      sigR: BytesLike;
      sigS: BytesLike;
      sigV: BigNumberish;
    },
    overrides: Partial<{
      userAddress: string;
      metaTxConfig: Partial<
        Omit<MetaTxConfig, "apiIds" | "forwarderAbi"> & { apiId: string }
      >;
      metaTransactionMethod: string;
    }> = {}
  ): Promise<TransactionResponse>
```

### `signNativeMetaTxApproveExchangeToken` (3 signatures)

Overload: returnTypedDataToSign is true → returns UnsignedMetaTx

```ts
public async signNativeMetaTxApproveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides: Partial<{ spender: string }> & { returnTypedDataToSign: true }
  ): Promise<UnsignedMetaTx>

public async signNativeMetaTxApproveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides?: Partial<{ spender: string; returnTypedDataToSign?: false }>
  ): Promise<SignedMetaTx>

public async signNativeMetaTxApproveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides: Partial<{
      spender: string;
      returnTypedDataToSign: boolean;
    }> = {}
  ): Promise<SignedMetaTx | UnsignedMetaTx>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Offers

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/offers

> Public methods on the Offers mixin of @bosonprotocol/core-sdk.

# `Offers` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `OfferMixin`_

_Source: [`packages/core-sdk/src/offers/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/offers/mixin.ts)_



## Methods (27)

`approveExchangeToken`, `checkExchangePolicy`, `checkTokenGatedCondition`, `createOffer`, `createOfferBatch`, `extendOffer`, `extendOfferBatch`, `getCreatedBuyerIdFromLogs`, `getCreatedGroupIdsFromLogs`, `getCreatedOfferIdFromLogs`, `getCreatedOfferIdsFromLogs`, `getCreatedSellerIdFromLogs`, `getExchangeTokenAllowance`, `getExchangeTokenInfo`, `getOfferById`, `getOfferHash`, `getOffers`, `getProtocolAllowance`, `renderContractualAgreement`, `renderContractualAgreementForOffer`, `reserveRange`, `updateOfferRoyaltyRecipients`, `updateOfferRoyaltyRecipientsBatch`, `voidNonListedOffer`, `voidNonListedOfferBatch`, `voidOffer`, `voidOfferBatch`

## Signatures

### `approveExchangeToken` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async approveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides: Partial<{
      spender: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async approveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides?: Partial<{
      spender: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async approveExchangeToken(
    exchangeToken: string,
    value: BigNumberish,
    overrides: Partial<{
      spender: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `checkExchangePolicy` (1 signature)

Check a given offer meets ExchangePolicy rules.

```ts
public async checkExchangePolicy(
    offerId: BigNumberish,
    rules: offers.CheckExchangePolicyRules
  ): Promise<offers.CheckExchangePolicyResult>
```

### `checkTokenGatedCondition` (1 signature)

```ts
public async checkTokenGatedCondition(
    offerId: subgraph.OfferFieldsFragment["id"],
    buyerAddress: string
  ): Promise<boolean>
```

### `createOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createOffer(
    offerToCreate: offers.CreateOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createOffer(
    offerToCreate: offers.CreateOfferArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createOffer(
    offerToCreate: offers.CreateOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createOfferBatch` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createOfferBatch(
    offersToCreate: offers.CreateOfferArgs[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createOfferBatch(
    offersToCreate: offers.CreateOfferArgs[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async createOfferBatch(
    offersToCreate: offers.CreateOfferArgs[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `extendOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async extendOffer(
    offerId: BigNumberish,
    validUntil: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async extendOffer(
    offerId: BigNumberish,
    validUntil: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async extendOffer(
    offerId: BigNumberish,
    validUntil: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `extendOfferBatch` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async extendOfferBatch(
    offerIds: BigNumberish[],
    validUntil: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async extendOfferBatch(
    offerIds: BigNumberish[],
    validUntil: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async extendOfferBatch(
    offerIds: BigNumberish[],
    validUntil: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getCreatedBuyerIdFromLogs` (1 signature)

Utility method to retrieve the created `buyerId` from logs after calling `createBuyer`

```ts
public getCreatedBuyerIdFromLogs(logs: Log[]): string | null {
    const buyerId = getValueFromLogs<BigNumber>({
      iface: accounts.iface.bosonAccountHandlerIface,
      logs,
      eventArgsKey: "buyerId",
      eventName: "BuyerCreated"
    })
```

### `getCreatedGroupIdsFromLogs` (1 signature)

Utility method to retrieve the created `groupIds` from logs after calling `createGroup`

```ts
public getCreatedGroupIdsFromLogs(logs: Log[]): string[] {
    return getValuesFromLogs<BigNumber>({
      iface: groups.iface.bosonGroupHandlerIface,
      logs,
      eventArgsKey: "groupId",
      eventName: "GroupCreated"
    }).map((g) => g.toString())
```

### `getCreatedOfferIdFromLogs` (1 signature)

Utility method to retrieve the created `offerId` from logs after calling `createOffer` or `createOfferAndSeller`.

```ts
public getCreatedOfferIdFromLogs(logs: Log[]): string | null {
    const offerId = getValueFromLogs<BigNumber>({
      iface: offers.iface.bosonOfferHandlerIface,
      logs,
      eventArgsKey: "offerId",
      eventName: "OfferCreated"
    })
```

### `getCreatedOfferIdsFromLogs` (1 signature)

Utility method to retrieve the created `offerIds` from logs after calling `createOfferBatch`

```ts
public getCreatedOfferIdsFromLogs(logs: Log[]): string[] {
    return getValuesFromLogs<BigNumber>({
      iface: offers.iface.bosonOfferHandlerIface,
      logs,
      eventArgsKey: "offerId",
      eventName: "OfferCreated"
    }).map((o) => o.toString())
```

### `getCreatedSellerIdFromLogs` (1 signature)

Utility method to retrieve the created `sellerId` from logs after calling `createSeller` or `createOfferAndSeller`.

```ts
public getCreatedSellerIdFromLogs(logs: Log[]): string | null {
    const sellerId = getValueFromLogs<BigNumber>({
      iface: accounts.iface.bosonAccountHandlerIface,
      logs,
      eventArgsKey: "sellerId",
      eventName: "SellerCreated"
    })
```

### `getExchangeTokenAllowance` (1 signature)

Returns the current allowance of the given token by calling the contract.

```ts
public async getExchangeTokenAllowance(
    exchangeToken: string,
    overrides: Partial<{
      spender: string;
      owner: string;
    }> = {}
  ): Promise<string>
```

### `getExchangeTokenInfo` (1 signature)

Returns `name`, `decimals` and `symbol` of the given token by calling the contract.

```ts
public async getExchangeTokenInfo(
    exchangeToken: string
  ): Promise<ITokenInfo | undefined>
```

### `getOfferById` (1 signature)

Returns offer from subgraph.

```ts
public async getOfferById(
    offerId: BigNumberish,
    queryVars?: offers.subgraph.SingleOfferQueryVariables
  ): Promise<subgraph.OfferFieldsFragment>
```

### `getOfferHash` (1 signature)

```ts
public async getOfferHash(
    fullOfferArgsUnsigned: Omit<FullOfferArgs, "signature">,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  )
```

### `getOffers` (1 signature)

Returns offers from subgraph.

```ts
public async getOffers(
    queryVars?: subgraph.GetOffersQueryQueryVariables
  ): Promise<subgraph.OfferFieldsFragment[]>
```

### `getProtocolAllowance` (1 signature)

```ts
public async getProtocolAllowance(
    exchangeToken: string,
    overrides: Partial<{
      spender: string;
      owner: string;
    }> = {}
  ): Promise<string>
```

### `renderContractualAgreement` (1 signature)

Renders contractual agreement for given offer.

```ts
public async renderContractualAgreement(
    template: string,
    offerData: offers.CreateOfferArgs,
    offerMetadata: offers.AdditionalOfferMetadata
  ): Promise<string>
```

### `renderContractualAgreementForOffer` (1 signature)

Renders contractual agreement for given offer.

```ts
public async renderContractualAgreementForOffer(
    offerId: BigNumberish
  ): Promise<string>
```

### `reserveRange` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async reserveRange(
    offerId: BigNumberish,
    length: BigNumberish,
    to: "seller" | "contract",
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async reserveRange(
    offerId: BigNumberish,
    length: BigNumberish,
    to: "seller" | "contract",
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async reserveRange(
    offerId: BigNumberish,
    length: BigNumberish,
    to: "seller" | "contract",
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `updateOfferRoyaltyRecipients` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async updateOfferRoyaltyRecipients(
    offerId: BigNumberish,
    royaltyInfo: RoyaltyInfo,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async updateOfferRoyaltyRecipients(
    offerId: BigNumberish,
    royaltyInfo: RoyaltyInfo,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async updateOfferRoyaltyRecipients(
    offerId: BigNumberish,
    royaltyInfo: RoyaltyInfo,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `updateOfferRoyaltyRecipientsBatch` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async updateOfferRoyaltyRecipientsBatch(
    offerIds: BigNumberish[],
    royaltyInfo: RoyaltyInfo,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async updateOfferRoyaltyRecipientsBatch(
    offerIds: BigNumberish[],
    royaltyInfo: RoyaltyInfo,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async updateOfferRoyaltyRecipientsBatch(
    offerIds: BigNumberish[],
    royaltyInfo: RoyaltyInfo,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `voidNonListedOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async voidNonListedOffer(
    fullOffer: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async voidNonListedOffer(
    fullOffer: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async voidNonListedOffer(
    fullOffer: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `voidNonListedOfferBatch` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async voidNonListedOfferBatch(
    fullOffers: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async voidNonListedOfferBatch(
    fullOffers: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async voidNonListedOfferBatch(
    fullOffers: Omit<
      FullOfferArgs,
      | "offerCreator"
      | "committer"
      | "signature"
      | "conditionalTokenId"
      | "sellerOfferParams"
    >[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `voidOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async voidOffer(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async voidOffer(
    offerId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async voidOffer(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `voidOfferBatch` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async voidOfferBatch(
    offerIds: BigNumberish[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async voidOfferBatch(
    offerIds: BigNumberish[],
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async voidOfferBatch(
    offerIds: BigNumberish[],
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Orchestration

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/orchestration

> Public methods on the Orchestration mixin of @bosonprotocol/core-sdk.

# `Orchestration` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `OrchestrationMixin`_

_Source: [`packages/core-sdk/src/orchestration/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/orchestration/mixin.ts)_



## Methods (10)

`commitToConditionalOfferAndRedeemVoucher`, `commitToOfferAndRedeemVoucher`, `createOfferCommitAndRedeem`, `createOfferWithCondition`, `createPremintedOfferAddToGroup`, `createPremintedOfferWithCondition`, `createSellerAndOfferWithCondition`, `createSellerAndPremintedOffer`, `createSellerAndPremintedOfferWithCondition`, `raiseAndEscalateDispute`

## Signatures

### `commitToConditionalOfferAndRedeemVoucher` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async commitToConditionalOfferAndRedeemVoucher(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToConditionalOfferAndRedeemVoucher(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async commitToConditionalOfferAndRedeemVoucher(
    offerId: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `commitToOfferAndRedeemVoucher` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async commitToOfferAndRedeemVoucher(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToOfferAndRedeemVoucher(
    offerId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async commitToOfferAndRedeemVoucher(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createOfferCommitAndRedeem` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createOfferCommitAndRedeem(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createOfferCommitAndRedeem(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createOfferCommitAndRedeem(
    createOfferAndCommitArgs: FullOfferArgs,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createOfferWithCondition` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createPremintedOfferAddToGroup` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createPremintedOfferAddToGroup(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    groupId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createPremintedOfferAddToGroup(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    groupId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createPremintedOfferAddToGroup(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    groupId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createPremintedOfferWithCondition` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createPremintedOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createPremintedOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createPremintedOfferWithCondition(
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createSellerAndOfferWithCondition` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createSellerAndOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createSellerAndOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createSellerAndOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createSellerAndPremintedOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createSellerAndPremintedOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createSellerAndPremintedOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createSellerAndPremintedOffer(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `createSellerAndPremintedOfferWithCondition` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async createSellerAndPremintedOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async createSellerAndPremintedOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async createSellerAndPremintedOfferWithCondition(
    sellerToCreate: accounts.CreateSellerArgs,
    offerToCreate: offers.CreateOfferArgs,
    premintParameters: PremintParametersStruct,
    condition: ConditionStruct,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `raiseAndEscalateDispute` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async raiseAndEscalateDispute(
    exchangeId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async raiseAndEscalateDispute(
    exchangeId: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      returnTxInfo?: false;
    }>
  ): Promise<TransactionResponse>

public async raiseAndEscalateDispute(
    exchangeId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Price discovery

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/price-discovery

> Public methods on the Price discovery mixin of @bosonprotocol/core-sdk.

# `Price discovery` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `PriceDiscoveryMixin`_

_Source: [`packages/core-sdk/src/price-discovery/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/price-discovery/mixin.ts)_



## Methods (1)

`commitToPriceDiscoveryOffer`

## Signatures

### `commitToPriceDiscoveryOffer` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async commitToPriceDiscoveryOffer(
    buyer: string,
    tokenIdOrOfferId: BigNumberish,
    priceDiscovery: PriceDiscoveryStruct,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async commitToPriceDiscoveryOffer(
    buyer: string,
    tokenIdOrOfferId: BigNumberish,
    priceDiscovery: PriceDiscoveryStruct,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async commitToPriceDiscoveryOffer(
    buyer: string,
    tokenIdOrOfferId: BigNumberish,
    priceDiscovery: PriceDiscoveryStruct,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Protocol config

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/protocol-config

> Public methods on the Protocol config mixin of @bosonprotocol/core-sdk.

# `Protocol config` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `ProtocolConfigMixin`_

_Source: [`packages/core-sdk/src/protocol-config/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/protocol-config/mixin.ts)_



## Methods (1)

`getMaxRoyaltyPercentage`

## Signatures

### `getMaxRoyaltyPercentage` (1 signature)

```ts
public async getMaxRoyaltyPercentage(
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  ): Promise<number>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Seaport

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/seaport

> Public methods on the Seaport mixin of @bosonprotocol/core-sdk.

# `Seaport` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `SeaportMixin`_

_Source: [`packages/core-sdk/src/seaport/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/seaport/mixin.ts)_

_No public methods detected — this mixin is likely composition-only._



## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Search

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/search

> Public methods on the Search mixin of @bosonprotocol/core-sdk.

# `Search` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `SearchMixin`_

_Source: [`packages/core-sdk/src/search/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/search/mixin.ts)_



## Methods (1)

`searchProducts`

## Signatures

### `searchProducts` (1 signature)

Search for products matching the given keywords. By default, only products that are currently valid (based on their validity dates) are returned. This behavior can be controlled via the `includeInvalidOffers` option in the queryVars parameter. ordering (productsOrderBy, productsOrderDirection), filtering (productsFilter), and includeInvalidOffers flag to control validity filtering.

```ts
public async searchProducts(
    keywords: string[],
    queryVars?: subgraph.SearchProductsQueryQueryVariables & {
      includeInvalidOffers?: boolean;
    }
  ): Promise<subgraph.ProductSearchResultFieldsFragment[]>
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Core SDK: Subgraph (client)

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/subgraph-client

> Public methods on the Subgraph (client) mixin of @bosonprotocol/core-sdk.

# `Subgraph (client)` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `SubgraphMixin`_

_Source: [`packages/core-sdk/src/subgraph/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/subgraph/mixin.ts)_



## Methods (2)

`getSubgraphBlockNumber`, `waitForGraphNodeIndexing`

## Signatures

### `getSubgraphBlockNumber` (1 signature)

```ts
public async getSubgraphBlockNumber(): Promise<number> {
    const client = new GraphQLClient(this._subgraphUrl)
```

### `waitForGraphNodeIndexing` (1 signature)

```ts
public async waitForGraphNodeIndexing(
    blockNumberOrTransaction?: number | TransactionResponse | TransactionReceipt
  )
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — Types & enums

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/types

> Generated from @bosonprotocol/common and core-sdk type definitions.

# Types & enums

> :::info
> **Auto-generated stub** — regenerated from `@bosonprotocol/common` and `@bosonprotocol/core-sdk` type definitions.
> :::

Key types you'll encounter:

- `Offer`, `OfferDates`, `OfferDurations`
- `Exchange`, `ExchangeState`
- `Dispute`, `DisputeState`
- `Seller`, `Buyer`, `DisputeResolver`, `Agent`
- `Condition`, `TokenType`, `EvaluationMethod`, `GatingType`
- `MetaTransactionConfig`, `MetaTxConfig`
- `Web3LibAdapter`, `MetadataStorage`

Enum values:

- `ExchangeState`: `Committed | Redeemed | Disputed | Completed | Cancelled | Revoked | Expired`
- `DisputeState`: `Resolving | Retracted | Resolved | Decided | Refused | Escalated | Expired`
- `TokenType`: `0=ERC20 | 1=ERC721 | 2=ERC1155`
- `EvaluationMethod`: `0=None | 1=Threshold | 2=TokenRange`
- `GatingType`: `0=PerAddress | 1=PerTokenId`

## Source

- [`@bosonprotocol/common/src`](https://github.com/bosonprotocol/core-components/tree/main/packages/common/src)

---

# Reference — Core SDK: Voucher

URL: https://www.bosonprotocol.io/docs/reference/core-sdk/voucher

> Public methods on the Voucher mixin of @bosonprotocol/core-sdk.

# `Voucher` mixin

:::info
**Generated from `core-components/packages/core-sdk/src/<domain>/mixin.ts`. Edit the TypeScript source, not this page.**
:::

_Class: `VoucherMixin`_

_Source: [`packages/core-sdk/src/voucher/mixin.ts`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/voucher/mixin.ts)_



## Methods (10)

`approveProtocolForAll`, `burnPremintedVouchers`, `getAvailablePreMints`, `getRangeByOfferId`, `isApprovedForAll`, `preMint`, `setApprovalForAllToContract`, `setContractURI`, `transferFrom`, `validateSeaportOrders`

## Signatures

### `approveProtocolForAll` (1 signature)

```ts
public async approveProtocolForAll(
    overrides: Partial<{
      operator: string;
      contractAddress: string;
    }> = {}
  )
```

### `burnPremintedVouchers` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async burnPremintedVouchers(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async burnPremintedVouchers(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async burnPremintedVouchers(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `getAvailablePreMints` (1 signature)

Gets the number of vouchers available to be pre-minted for an offer.

```ts
public async getAvailablePreMints(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  ): Promise<string>
```

### `getRangeByOfferId` (1 signature)

Gets the range for an offer.

```ts
public async getRangeByOfferId(
    offerId: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  ): Promise<Range>
```

### `isApprovedForAll` (1 signature)

```ts
public async isApprovedForAll(
    operator: string,
    overrides: Partial<{
      owner: string;
      contractAddress: string;
    }> = {}
  )
```

### `preMint` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async preMint(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async preMint(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides?: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async preMint(
    offerId: BigNumberish,
    amount: BigNumberish,
    overrides: Partial<{
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `setApprovalForAllToContract` (1 signature)

```ts
public async setApprovalForAllToContract(
    operator: string,
    approved: boolean,
    overrides: Partial<{
      contractAddress: string;
    }> = {}
  )
```

### `setContractURI` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async setContractURI(
    contractURI: string,
    collectionIndex: BigNumberish,
    overrides: Partial<{
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async setContractURI(
    contractURI: string,
    collectionIndex: BigNumberish,
    overrides?: Partial<{
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async setContractURI(
    contractURI: string,
    collectionIndex: BigNumberish,
    overrides: Partial<{
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `transferFrom` (3 signatures)

Overload: returnTxInfo is true → returns TransactionRequest

```ts
public async transferFrom(
    offerId: BigNumberish,
    to: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      owner: BigNumberish;
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo: true;
    }>
  ): Promise<TransactionRequest>

public async transferFrom(
    offerId: BigNumberish,
    to: BigNumberish,
    tokenId: BigNumberish,
    overrides?: Partial<{
      owner: BigNumberish;
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: false | undefined;
    }>
  ): Promise<TransactionResponse>

public async transferFrom(
    offerId: BigNumberish,
    to: BigNumberish,
    tokenId: BigNumberish,
    overrides: Partial<{
      owner: BigNumberish;
      contractAddress: string;
      txRequest: TransactionRequest;
      returnTxInfo?: boolean;
    }> = {}
  ): Promise<TransactionResponse | TransactionRequest>
```

### `validateSeaportOrders` (1 signature)

```ts
public async validateSeaportOrders(
    openseaConduit: string,
    seaportContract: string,
    orders: SeaportOrder[],
    overrides: Partial<{
      contractAddress: string;
      approveIfNeeded: boolean;
    }> = { approveIfNeeded: true }
  )
```

## Related

- [Reference → CoreSDK class](./core-sdk) — how mixins compose.
- [Concepts → The Boson model](/concepts/model).

---

# Reference — MCP tools

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools

> All 54 MCP tools, auto-generated from the live agentic-commerce server's tools/list.

# MCP tools

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schemas in the source repo, not this page.**
:::

For the integration overview, see [Tooling → MCP](/tooling/mcp). For the canonical signing flow, see [Build for AI agents → The 3-step signing pattern](/agents/signing).

### Seller & buyer

- [`create_buyer`](./mcp-tools/create_buyer) — Creates a buyer account for signerAddress.
- [`create_seller`](./mcp-tools/create_seller) — Creates a seller account on Boson Protocol.
- [`get_sellers`](./mcp-tools/get_sellers) — Reads seller account entities from the Boson subgraph.
- [`get_sellers_by_address`](./mcp-tools/get_sellers_by_address) — Reads seller entities associated with a specific Ethereum address.
- [`update_seller`](./mcp-tools/update_seller) — Updates an existing seller account.

### Offer management

- [`create_offer`](./mcp-tools/create_offer) — Creates a product offer.
- [`create_offer_with_condition`](./mcp-tools/create_offer_with_condition) — Creates an offer gated by token-ownership (e.g.
- [`get_offers`](./mcp-tools/get_offers) — Reads offer listings from the Boson subgraph.
- [`render_contractual_agreement`](./mcp-tools/render_contractual_agreement) — Renders the legal contractual agreement text/HTML for an offer using its offer data and metadata.
- [`sign_full_offer`](./mcp-tools/sign_full_offer) — Generates EIP-712 typed data for a non-listed (private) offer that the offer creator must sign.
- [`store_base_metadata`](./mcp-tools/store_base_metadata) — Stores a Base metadata object to IPFS.
- [`store_bundle_item_nft_metadata`](./mcp-tools/store_bundle_item_nft_metadata) — Stores a single NFT bundle item's metadata to IPFS.
- [`store_bundle_item_product_v1_metadata`](./mcp-tools/store_bundle_item_product_v1_metadata) — Stores a single ProductV1 bundle item's metadata to IPFS.
- [`store_bundle_metadata`](./mcp-tools/store_bundle_metadata) — Stores a Bundle metadata object to IPFS.
- [`store_product_v1_metadata`](./mcp-tools/store_product_v1_metadata) — Stores a ProductV1 metadata object to IPFS.
- [`validate_metadata`](./mcp-tools/validate_metadata) — Validates a metadata object against the Boson Protocol schema (PRODUCT_V1, BUNDLE, BASE, etc.) without storing it.
- [`void_non_listed_offer`](./mcp-tools/void_non_listed_offer) — Voids a private (non-listed) offer before it is fulfilled.
- [`void_non_listed_offer_batch`](./mcp-tools/void_non_listed_offer_batch) — Voids multiple private offers atomically.
- [`void_offer`](./mcp-tools/void_offer) — Voids a listed offer so it can no longer be committed to.

### Exchange management

- [`approve_exchange_token`](./mcp-tools/approve_exchange_token) — Grants ERC-20 allowance to the Boson Protocol contract.
- [`cancel_voucher`](./mcp-tools/cancel_voucher) — Cancels a committed voucher.
- [`commit_to_buyer_offer`](./mcp-tools/commit_to_buyer_offer) — Fulfils a buyer-initiated offer (creator='BUYER') by the seller.
- [`commit_to_offer`](./mcp-tools/commit_to_offer) — Commits to an offer, creating an exchange and minting a voucher NFT.
- [`complete_exchange`](./mcp-tools/complete_exchange) — Completes an exchange after the dispute period expires, releasing funds to the seller.
- [`create_offer_and_commit`](./mcp-tools/create_offer_and_commit) — Atomically creates a private offer and commits a specific buyer in one transaction.
- [`get_exchanges`](./mcp-tools/get_exchanges) — Reads exchange records (offer commitments) from the Boson subgraph.
- [`redeem_voucher`](./mcp-tools/redeem_voucher) — Redeems a voucher, signalling physical receipt of goods and starting the dispute period clock.
- [`revoke_voucher`](./mcp-tools/revoke_voucher) — Revokes a committed (not yet redeemed) voucher on behalf of the seller, returning funds to the buyer.

### Dispute management

- [`create_dispute_resolution_proposal`](./mcp-tools/create_dispute_resolution_proposal) — Generates EIP-712 typed data for a mutual dispute resolution proposal.
- [`decide_dispute`](./mcp-tools/decide_dispute) — Decides an escalated dispute.
- [`escalate_dispute`](./mcp-tools/escalate_dispute) — Escalates a stale dispute to the third-party dispute resolver.
- [`expire_dispute`](./mcp-tools/expire_dispute) — Marks a dispute as expired after its resolution period passes.
- [`expire_dispute_batch`](./mcp-tools/expire_dispute_batch) — Marks multiple expired disputes in one transaction.
- [`expire_escalated_dispute`](./mcp-tools/expire_escalated_dispute) — Expires an escalated dispute once the resolver's response period passes without a decision.
- [`extend_dispute_timeout`](./mcp-tools/extend_dispute_timeout) — Extends the deadline of an active dispute.
- [`get_dispute_by_id`](./mcp-tools/get_dispute_by_id) — Reads a single dispute by its ID (equals the exchangeId).
- [`get_dispute_resolvers`](./mcp-tools/get_dispute_resolvers) — Reads registered dispute resolver entities.
- [`get_disputes`](./mcp-tools/get_disputes) — Reads dispute records from the Boson subgraph.
- [`raise_dispute`](./mcp-tools/raise_dispute) — Raises a dispute on a redeemed exchange.
- [`refuse_escalated_dispute`](./mcp-tools/refuse_escalated_dispute) — Dispute resolver refuses to decide an escalated dispute.
- [`resolve_dispute`](./mcp-tools/resolve_dispute) — Resolves a dispute by mutual agreement.
- [`retract_dispute`](./mcp-tools/retract_dispute) — Retracts a raised dispute, releasing seller deposit and restoring completion flow.

### Funds

- [`deposit_funds`](./mcp-tools/deposit_funds) — Deposits ERC-20 or native tokens into an entity's protocol treasury (e.g.
- [`get_funds`](./mcp-tools/get_funds) — Reads treasury fund balances for sellers and buyers from the Boson subgraph.
- [`withdraw_funds`](./mcp-tools/withdraw_funds) — Withdraws funds from an entity's protocol treasury to the entity's treasury address.

### Meta-transactions & broadcast

- [`send_forwarded_meta_transaction`](./mcp-tools/send_forwarded_meta_transaction) — Relays a Biconomy forwarded meta-transaction (ERC-20 gas payment).
- [`send_meta_transaction`](./mcp-tools/send_meta_transaction) — Relays a pre-signed meta-transaction via Biconomy so the user pays no gas.
- [`send_native_meta_transaction`](./mcp-tools/send_native_meta_transaction) — Relays a native meta-transaction (EIP-712 signed function call) via Biconomy.
- [`send_signed_transaction`](./mcp-tools/send_signed_transaction) — Broadcasts a signed raw Ethereum transaction to the network.

### Agent registry

- [`get_registered_agents`](./mcp-tools/get_registered_agents) — Returns all dACP agents registered with this MCP server instance, with their associated protocol entities and roles.
- [`register_agent`](./mcp-tools/register_agent) — Registers a dACP agent with this MCP server instance, associating its Ethereum identities and roles.

### Configuration

- [`get_config_ids`](./mcp-tools/get_config_ids) — Returns all valid configId values for this server.
- [`get_supported_tokens`](./mcp-tools/get_supported_tokens) — Returns ERC-20 tokens accepted as exchange tokens on the given configId deployment.

### Other

- [`get_all_products_with_not_voided_variants`](./mcp-tools/get_all_products_with_not_voided_variants) — Reads product groupings with at least one non-voided variant from the Boson subgraph.

## Per-tool page format

Each tool's page includes:

- **Description** — the tool's purpose, from the server.
- **Category** — heuristic grouping (seller/buyer, offer, exchange, dispute, funds, meta-tx, agent registry, config).
- **Returns unsigned tx?** — heuristic flag.
- **Input schema** — auto-generated table from the JSON Schema reported by the server.
- **Related** — links to the SSoT signing page and the integration overview.

## Source

- Server: `https://mcp-staging.bosonprotocol.io/mcp`
- Schema authority: [`@bosonprotocol/agentic-commerce/src/boson/mcp-server`](https://github.com/bosonprotocol/agentic-commerce/tree/main/src/boson/mcp-server)
- Example flows: [`agentic-commerce/e2e/boson/tests/complete-marketplace-journeys.test.ts`](https://github.com/bosonprotocol/agentic-commerce/blob/main/e2e/boson/tests/complete-marketplace-journeys.test.ts)

---

# approve_exchange_token

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/approve_exchange_token

> Grants ERC-20 allowance to the Boson Protocol contract.

# `approve_exchange_token`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Grants ERC-20 allowance to the Boson Protocol contract. Must be called before commit_to_offer or deposit_funds when using non-native exchange tokens. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeTokenAddress` | string | yes | ERC-20 token contract address to approve for the Boson Protocol diamond. |
| `amount` | string | yes | Allowance in wei. Use max uint256 string for unlimited: '115792089237316195423570985008687907853269984665640564039457584007913129639935'. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# cancel_voucher

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/cancel_voucher

> Cancels a committed voucher.

# `cancel_voucher`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Cancels a committed voucher. Caller must be the buyer (voucher holder). Buyer forfeits buyerCancellationPenalty; remainder is refunded. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# commit_to_buyer_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/commit_to_buyer_offer

> Fulfils a buyer-initiated offer (creator='BUYER') by the seller.

# `commit_to_buyer_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Fulfils a buyer-initiated offer (creator='BUYER') by the seller. Caller must be the seller. Provide matching collateral. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offerId` | string | yes | ID of a buyer-initiated offer (creator='BUYER') to commit to. The seller fulfils the offer. |
| `collectionIndex` | — | no |  |
| `royaltyInfo` | object | no |  |
| `drMutualizerAddress` | — | no | Valid Ethereum address (e.g. '0xAbCd...' or '0xabcd...'). Mixed-case addresses are checksum-validated; all-lowercase and all-uppercase addresses are also accepted. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# commit_to_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/commit_to_offer

> Commits to an offer, creating an exchange and minting a voucher NFT.

# `commit_to_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Commits to an offer, creating an exchange and minting a voucher NFT. Caller is the buyer (signerAddress) unless 'buyer' param is set. For ERC-20 offers, call approve_exchange_token first. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offerId` | string | yes | ID of the active offer to commit to. Creates an exchange and mints a voucher NFT. |
| `buyer` | string | no | Optional buyer address if different from signerAddress. When set, executionMode must be 'direct'. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# complete_exchange

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/complete_exchange

> Completes an exchange after the dispute period expires, releasing funds to the seller.

# `complete_exchange`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Completes an exchange after the dispute period expires, releasing funds to the seller. Can be called by seller after dispute period or by buyer at any time post-redemption. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_buyer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_buyer

> Creates a buyer account for signerAddress.

# `create_buyer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Creates a buyer account for signerAddress. Required before a buyer can commit to seller-initiated offers for the first time. No prerequisites. Returns unsigned transaction data.

**Category:** Seller & buyer.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_dispute_resolution_proposal

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_dispute_resolution_proposal

> Generates EIP-712 typed data for a mutual dispute resolution proposal.

# `create_dispute_resolution_proposal`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Generates EIP-712 typed data for a mutual dispute resolution proposal. Both buyer and seller must sign the same buyerPercentBasisPoints value locally with their wallet (EIP-712) before calling resolve_dispute. Returns: typed data structure (domain, types, message).

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `buyerPercentBasisPoints` | — | yes | Proposed percentage of disputed funds for the buyer, 0–10000 (basis points). The counterparty must sign this same value. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_offer

> Creates a product offer.

# `create_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Creates a product offer. Caller must have a seller account (create_seller first). Prerequisite: store metadata first with store_product_v1_metadata or store_base_metadata to get metadataUri/metadataHash. All dates in milliseconds; amounts as strings in wei. Returns unsigned tx — sign locally with your wallet → send_signed_transaction, or executionMode='metaTx'.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `metadataUri` | string | yes | IPFS URI pointing to the offer metadata JSON. Obtain by calling store_product_v1_metadata, store_bundle_metadata, or store_base_metadata. |
| `metadataHash` | string | yes | Keccak256 hash of the metadata JSON. Returned alongside metadataUri from the store_*_metadata tools. |
| `exchangeTokenAddress` | string | no | ERC-20 token accepted for payment. Omit or use address(0) for native ETH. Call get_supported_tokens for valid values. |
| `price` | string | yes | Offer price in the exchange token's smallest unit (wei). Pass as string to avoid precision loss, e.g. '1000000000000000000' = 1 ETH. |
| `sellerDeposit` | — | yes | Seller collateral in same unit as price. Released to seller on completion or forfeited on dispute. Pass as string. |
| `agentId` | — | no | Optional dACP agent facilitating this offer. Omit or pass '0' if no agent. |
| `buyerCancellationPenalty` | — | yes | Amount buyer forfeits on cancel, in same unit as price. Must be &lt;= price. Pass as string. |
| `quantityAvailable` | number | yes | How many times this offer can be committed to. Must be 1 when creator='BUYER'. |
| `validFromDateInMS` | number | yes | Unix timestamp in milliseconds when the offer becomes active. Example: Date.now() for immediate. |
| `validUntilDateInMS` | number | yes | Unix timestamp in milliseconds when the offer can no longer be committed to. |
| `voucherRedeemableFromDateInMS` | number | yes | Timestamp in ms from which buyer can redeem. Must be &gt;= validFromDateInMS. |
| `voucherRedeemableUntilDateInMS` | number | yes | Timestamp in ms after which voucher cannot be redeemed. Set to 0 to use voucherValidDurationInMS instead. |
| `disputePeriodDurationInMS` | number | yes | Duration in ms for buyer to raise a dispute after redeeming. Example: 604800000 = 7 days. |
| `voucherValidDurationInMS` | number | yes | Voucher is redeemable for this many ms after commit. Set to 0 to use voucherRedeemableUntilDateInMS instead. |
| `resolutionPeriodDurationInMS` | number | yes | Duration in ms to respond to a resolution proposal before it expires. Example: 259200000 = 3 days. |
| `disputeResolverId` | string | no | ID of the dispute resolver for escalated disputes. Call get_dispute_resolvers to list available resolvers. |
| `collectionIndex` | — | no | Index of the seller's NFT collection for vouchers. Omit to use default (index 0). |
| `feeLimit` | — | no | Max protocol fee the seller accepts in same token unit. Pass as string. |
| `priceType` | number | no | 0 = static price, 1 = discovery price (auction). |
| `royaltyInfo` | object | no |  |
| `creator` | `SELLER` \| `BUYER` | no | 'SELLER' (default) = seller creates offer. 'BUYER' = buyer-initiated offer, quantity must be 1. |
| `drMutualizerAddress` | — | no | Optional dispute resolver mutualizer contract address that pools resolution funds. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_offer_and_commit

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_offer_and_commit

> Atomically creates a private offer and commits a specific buyer in one transaction.

# `create_offer_and_commit`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Atomically creates a private offer and commits a specific buyer in one transaction. Prerequisite: call sign_full_offer, sign the returned typed data locally with your wallet (EIP-712), and provide the signature here. Used for private/bilateral trades. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `signature` | string | yes | ECDSA signature over the offer typed data. Workflow: sign_full_offer → sign the returned typed data locally with your wallet (EIP-712) → use result here. |
| `offerCreator` | string | yes | Ethereum address of the seller creating this non-listed offer. Must match the seller's assistant address. |
| `committer` | — | yes | Ethereum address of the buyer committing in the same transaction. |
| `collectionIndex` | string | no | Index of the seller's NFT collection for vouchers. Omit to use default (index 0). |
| `royaltyInfo` | object | no |  |
| `drMutualizerAddress` | — | no | Optional dispute resolver mutualizer contract address that pools resolution funds. |
| `conditionalTokenId` | — | no | Optional token ID of the NFT gate token used by this specific commit (for SpecificToken gating type). |
| `condition` | object | no |  |
| `useDepositedFunds` | boolean | no | If true, use funds already deposited in the protocol treasury instead of transferring from the wallet. |
| `sellerId` | — | yes | Numeric ID of the seller entity. Obtain via get_sellers_by_address. |
| `buyerId` | — | yes | Numeric ID of the buyer entity. Use '0' for seller-initiated offers. |
| `metadataUri` | string | yes | IPFS URI pointing to the offer metadata JSON. Obtain by calling store_product_v1_metadata, store_bundle_metadata, or store_base_metadata. |
| `metadataHash` | string | yes | Keccak256 hash of the metadata JSON. Returned alongside metadataUri from the store_*_metadata tools. |
| `exchangeTokenAddress` | — | no | ERC-20 token accepted for payment. Omit or use address(0) for native ETH. Call get_supported_tokens for valid values. |
| `price` | — | yes | Offer price in the exchange token's smallest unit (wei). Pass as string to avoid precision loss, e.g. '1000000000000000000' = 1 ETH. |
| `sellerDeposit` | — | yes | Seller collateral in same unit as price. Released to seller on completion or forfeited on dispute. Pass as string. |
| `agentId` | — | no | Optional dACP agent facilitating this offer. Omit or pass '0' if no agent. |
| `buyerCancellationPenalty` | — | yes | Amount buyer forfeits on cancel, in same unit as price. Must be &lt;= price. Pass as string. |
| `quantityAvailable` | number | yes | How many times this offer can be committed to. Must be 1 when creator='BUYER'. |
| `validFromDateInMS` | number | yes | Unix timestamp in milliseconds when the offer becomes active. Example: Date.now() for immediate. |
| `validUntilDateInMS` | number | yes | Unix timestamp in milliseconds when the offer can no longer be committed to. |
| `voucherRedeemableFromDateInMS` | number | yes | Timestamp in ms from which buyer can redeem. Must be &gt;= validFromDateInMS. |
| `voucherRedeemableUntilDateInMS` | number | yes | Timestamp in ms after which voucher cannot be redeemed. Set to 0 to use voucherValidDurationInMS instead. |
| `disputePeriodDurationInMS` | number | yes | Duration in ms for buyer to raise a dispute after redeeming. Example: 604800000 = 7 days. |
| `voucherValidDurationInMS` | number | yes | Voucher is redeemable for this many ms after commit. Set to 0 to use voucherRedeemableUntilDateInMS instead. |
| `resolutionPeriodDurationInMS` | number | yes | Duration in ms to respond to a resolution proposal before it expires. Example: 259200000 = 3 days. |
| `disputeResolverId` | string | no | ID of the dispute resolver for escalated disputes. Call get_dispute_resolvers to list available resolvers. |
| `feeLimit` | — | no | Max protocol fee the seller accepts in same token unit. Pass as string. |
| `priceType` | number | no | 0 = static price, 1 = discovery price (auction). |
| `creator` | `SELLER` \| `BUYER` | no | 'SELLER' (default) = seller creates offer. 'BUYER' = buyer-initiated offer, quantity must be 1. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_offer_with_condition

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_offer_with_condition

> Creates an offer gated by token-ownership (e.g.

# `create_offer_with_condition`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Creates an offer gated by token-ownership (e.g. hold an ERC-721 to commit). Same prerequisites as create_offer plus a condition object specifying the gate token, method, and threshold. Returns unsigned transaction data.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `condition` | object | yes |  |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `metadataUri` | string | yes | IPFS URI pointing to the offer metadata JSON. Obtain by calling store_product_v1_metadata, store_bundle_metadata, or store_base_metadata. |
| `metadataHash` | string | yes | Keccak256 hash of the metadata JSON. Returned alongside metadataUri from the store_*_metadata tools. |
| `exchangeTokenAddress` | — | no | ERC-20 token accepted for payment. Omit or use address(0) for native ETH. Call get_supported_tokens for valid values. |
| `price` | — | yes | Offer price in the exchange token's smallest unit (wei). Pass as string to avoid precision loss, e.g. '1000000000000000000' = 1 ETH. |
| `sellerDeposit` | — | yes | Seller collateral in same unit as price. Released to seller on completion or forfeited on dispute. Pass as string. |
| `agentId` | — | no | Optional dACP agent facilitating this offer. Omit or pass '0' if no agent. |
| `buyerCancellationPenalty` | — | yes | Amount buyer forfeits on cancel, in same unit as price. Must be &lt;= price. Pass as string. |
| `quantityAvailable` | number | yes | How many times this offer can be committed to. Must be 1 when creator='BUYER'. |
| `validFromDateInMS` | number | yes | Unix timestamp in milliseconds when the offer becomes active. Example: Date.now() for immediate. |
| `validUntilDateInMS` | number | yes | Unix timestamp in milliseconds when the offer can no longer be committed to. |
| `voucherRedeemableFromDateInMS` | number | yes | Timestamp in ms from which buyer can redeem. Must be &gt;= validFromDateInMS. |
| `voucherRedeemableUntilDateInMS` | number | yes | Timestamp in ms after which voucher cannot be redeemed. Set to 0 to use voucherValidDurationInMS instead. |
| `disputePeriodDurationInMS` | number | yes | Duration in ms for buyer to raise a dispute after redeeming. Example: 604800000 = 7 days. |
| `voucherValidDurationInMS` | number | yes | Voucher is redeemable for this many ms after commit. Set to 0 to use voucherRedeemableUntilDateInMS instead. |
| `resolutionPeriodDurationInMS` | number | yes | Duration in ms to respond to a resolution proposal before it expires. Example: 259200000 = 3 days. |
| `disputeResolverId` | string | no | ID of the dispute resolver for escalated disputes. Call get_dispute_resolvers to list available resolvers. |
| `collectionIndex` | — | no | Index of the seller's NFT collection for vouchers. Omit to use default (index 0). |
| `feeLimit` | — | no | Max protocol fee the seller accepts in same token unit. Pass as string. |
| `priceType` | number | no | 0 = static price, 1 = discovery price (auction). |
| `royaltyInfo` | object | no |  |
| `creator` | `SELLER` \| `BUYER` | no | 'SELLER' (default) = seller creates offer. 'BUYER' = buyer-initiated offer, quantity must be 1. |
| `drMutualizerAddress` | — | no | Optional dispute resolver mutualizer contract address that pools resolution funds. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# create_seller

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/create_seller

> Creates a seller account on Boson Protocol.

# `create_seller`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Creates a seller account on Boson Protocol. Required before creating any offers. signerAddress is automatically set as admin, assistant, and treasury. Provide seller metadata and royaltyPercentage. Returns unsigned transaction data.

**Category:** Seller & buyer.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `type` | string | yes |  |
| `name` | string | no |  |
| `description` | string | no |  |
| `legalTradingName` | string | no |  |
| `kind` | string | yes |  |
| `website` | string | no |  |
| `images` | object[] | no |  |
| `contactLinks` | object[] | no |  |
| `contactPreference` | string | yes |  |
| `socialLinks` | object[] | no |  |
| `salesChannels` | object[] | no |  |
| `contractUri` | string | yes | URI for OpenSea-style storefront metadata. Can be IPFS URI or empty string. |
| `royaltyPercentage` | string | yes | Default resale royalty in basis points (0–10000). Applied to all offers unless overridden. |
| `authTokenId` | — | yes | NFT token ID used as auth token (e.g. Lens profile ID). Pass '0' if not using auth tokens. |
| `authTokenType` | number | yes | Auth token type: 0=None, 1=Lens Protocol profile NFT. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# decide_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/decide_dispute

> Decides an escalated dispute.

# `decide_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Decides an escalated dispute. Caller must be the dispute resolver assigned to the offer's disputeResolverId. Specify buyerPercent in basis points (0=all to seller, 10000=all to buyer). Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `buyerPercent` | — | yes | Percentage of disputed funds to buyer in basis points (0–10000). 10000 = all to buyer, 0 = all to seller. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# deposit_funds

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/deposit_funds

> Deposits ERC-20 or native tokens into an entity's protocol treasury (e.g.

# `deposit_funds`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Deposits ERC-20 or native tokens into an entity's protocol treasury (e.g. seller deposit). For ERC-20, call approve_exchange_token first. Returns unsigned transaction data.

**Category:** Funds.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityId` | string | yes | Numeric ID of the entity to credit. Must match signerAddress's seller account. |
| `tokenAddress` | string | yes | ERC-20 token to deposit. Use address(0) for native ETH. |
| `amount` | — | yes | Amount in wei. For ERC-20, approve_exchange_token must be called first. Pass as string. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# escalate_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/escalate_dispute

> Escalates a stale dispute to the third-party dispute resolver.

# `escalate_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Escalates a stale dispute to the third-party dispute resolver. Caller must be the buyer. Resolver's escalation fee must be covered. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# expire_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/expire_dispute

> Marks a dispute as expired after its resolution period passes.

# `expire_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Marks a dispute as expired after its resolution period passes. Permissionless — anyone can call. Exchange must be in 'Disputed' state past its timeout. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# expire_dispute_batch

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/expire_dispute_batch

> Marks multiple expired disputes in one transaction.

# `expire_dispute_batch`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Marks multiple expired disputes in one transaction. All exchanges must be in 'Disputed' state past their respective timeouts. Permissionless. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeIds` | string[] | yes | Array of exchange IDs whose dispute period has passed. All must be in 'Disputed' state past their timeout. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# expire_escalated_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/expire_escalated_dispute

> Expires an escalated dispute once the resolver's response period passes without a decision.

# `expire_escalated_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Expires an escalated dispute once the resolver's response period passes without a decision. Permissionless — anyone can call. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# extend_dispute_timeout

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/extend_dispute_timeout

> Extends the deadline of an active dispute.

# `extend_dispute_timeout`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Extends the deadline of an active dispute. Dispute must be in 'Resolving' state. Either party can call this. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `newDisputeTimeout` | — | yes | New absolute Unix timestamp in SECONDS (not ms) for the dispute deadline. Must be later than current timeout. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_all_products_with_not_voided_variants

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_all_products_with_not_voided_variants

> Reads product groupings with at least one non-voided variant from the Boson subgraph.

# `get_all_products_with_not_voided_variants`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads product groupings with at least one non-voided variant from the Boson subgraph. Useful for storefront displays. Supports pagination and ordering. Read-only.

**Category:** Other.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `productsSkip` | number | no |  |
| `productsFirst` | number | no |  |
| `productsOrderBy` | `allVariantsVoided` \| `brand` \| `brand__id` \| `brand__name` \| `category` \| `category__id` \| `category__name` \| `description` \| `details_category` \| `details_offerCategory` \| `details_personalisation` \| `details_sections` \| `details_subCategory` \| `details_subCategory2` \| `details_tags` \| `disputeResolverId` \| `id` \| `identification_productId` \| `identification_productIdType` \| `identification_sKU` \| `maxValidFromDate` \| `maxValidUntilDate` \| `minValidFromDate` \| `minValidUntilDate` \| `notVoidedVariants` \| `offerCategory` \| `packaging_dimensions_height` \| `packaging_dimensions_length` \| `packaging_dimensions_unit` \| `packaging_dimensions_width` \| `packaging_packageQuantity` \| `packaging_weight_unit` \| `packaging_weight_value` \| `personalisation` \| `productV1Seller` \| `productV1Seller__contactPreference` \| `productV1Seller__defaultVersion` \| `productV1Seller__description` \| `productV1Seller__externalUrl` \| `productV1Seller__id` \| `productV1Seller__name` \| `productV1Seller__sellerId` \| `productV1Seller__tokenId` \| `productionInformation_brandName` \| `productionInformation_manufacturer` \| `productionInformation_manufacturerPartNumber` \| `productionInformation_materials` \| `productionInformation_modelNumber` \| `salesChannels` \| `sections` \| `sellerId` \| `subCategory` \| `subCategory2` \| `subCategory2__id` \| `subCategory2__name` \| `subCategory__id` \| `subCategory__name` \| `tags` \| `title` \| `uuid` \| `variants` \| `version` \| `visuals_images` \| `visuals_videos` | no |  |
| `productsOrderDirection` | `asc` \| `desc` | no |  |
| `productsFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_config_ids

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_config_ids

> Returns all valid configId values for this server.

# `get_config_ids`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Returns all valid configId values for this server. Call first to discover which network/deployment to use. No auth required.

**Category:** Configuration.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

_No input parameters._


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_dispute_by_id

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_dispute_by_id

> Reads a single dispute by its ID (equals the exchangeId).

# `get_dispute_by_id`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads a single dispute by its ID (equals the exchangeId). Read-only. Returns: dispute entity with state, timeout, buyerPercent. Use get_disputes to search first.

**Category:** Dispute management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `disputeId` | string | yes | Numeric ID of the dispute to retrieve. Note: disputeId equals the exchangeId of the associated exchange. |
| `queryVars` | — | no | Optional additional subgraph query variables for field selection. Leave empty for default fields. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_dispute_resolvers

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_dispute_resolvers

> Reads registered dispute resolver entities.

# `get_dispute_resolvers`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads registered dispute resolver entities. Use this to find a valid disputeResolverId for create_offer. Read-only. Returns: array of resolvers with ID, fees, escalationResponsePeriod, and supported tokens.

**Category:** Dispute management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `disputeResolversSkip` | number | no |  |
| `disputeResolversFirst` | number | no |  |
| `disputeResolversOrderBy` | `active` \| `admin` \| `assistant` \| `clerk` \| `escalationResponsePeriod` \| `fees` \| `funds` \| `id` \| `logs` \| `metadataUri` \| `offers` \| `pendingDisputeResolver` \| `pendingDisputeResolver__admin` \| `pendingDisputeResolver__assistant` \| `pendingDisputeResolver__clerk` \| `pendingDisputeResolver__id` \| `sellerAllowList` \| `treasury` | no |  |
| `disputeResolversOrderDirection` | `asc` \| `desc` | no |  |
| `disputeResolversFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_disputes

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_disputes

> Reads dispute records from the Boson subgraph.

# `get_disputes`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads dispute records from the Boson subgraph. Supports pagination, ordering, and filtering by buyer/seller/state. Read-only. Returns: array of dispute entities with exchangeId, state, timeout.

**Category:** Dispute management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `disputesSkip` | number | no |  |
| `disputesFirst` | number | no |  |
| `disputesOrderBy` | `buyer` \| `buyerPercent` \| `buyer__active` \| `buyer__id` \| `buyer__wallet` \| `decidedDate` \| `disputeResolver` \| `disputeResolver__active` \| `disputeResolver__admin` \| `disputeResolver__assistant` \| `disputeResolver__clerk` \| `disputeResolver__escalationResponsePeriod` \| `disputeResolver__id` \| `disputeResolver__metadataUri` \| `disputeResolver__treasury` \| `disputedDate` \| `escalatedDate` \| `exchange` \| `exchangeId` \| `exchange__cancelledDate` \| `exchange__committedDate` \| `exchange__completedDate` \| `exchange__disputed` \| `exchange__disputedDate` \| `exchange__expired` \| `exchange__finalizedDate` \| `exchange__id` \| `exchange__mutualizerAddress` \| `exchange__redeemedDate` \| `exchange__revokedDate` \| `exchange__state` \| `exchange__validUntilDate` \| `finalizedDate` \| `id` \| `refusedDate` \| `resolvedDate` \| `retractedDate` \| `seller` \| `seller__active` \| `seller__admin` \| `seller__assistant` \| `seller__authTokenId` \| `seller__authTokenType` \| `seller__clerk` \| `seller__id` \| `seller__metadataUri` \| `seller__sellerId` \| `seller__treasury` \| `seller__voucherCloneAddress` \| `state` \| `timeout` | no |  |
| `disputesOrderDirection` | `asc` \| `desc` | no |  |
| `disputesFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_exchanges

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_exchanges

> Reads exchange records (offer commitments) from the Boson subgraph.

# `get_exchanges`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads exchange records (offer commitments) from the Boson subgraph. Filter by buyer/seller/state. Read-only. Returns: array of exchanges with offerId, state (Committed/Redeemed/Completed/Disputed/Cancelled/Revoked), and voucher details.

**Category:** Exchange management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangesSkip` | number | no |  |
| `exchangesFirst` | number | no |  |
| `exchangesOrderBy` | `buyer` \| `buyer__active` \| `buyer__id` \| `buyer__wallet` \| `cancelledDate` \| `committedDate` \| `completedDate` \| `dispute` \| `disputeResolver` \| `disputeResolver__active` \| `disputeResolver__admin` \| `disputeResolver__assistant` \| `disputeResolver__clerk` \| `disputeResolver__escalationResponsePeriod` \| `disputeResolver__id` \| `disputeResolver__metadataUri` \| `disputeResolver__treasury` \| `dispute__buyerPercent` \| `dispute__decidedDate` \| `dispute__disputedDate` \| `dispute__escalatedDate` \| `dispute__exchangeId` \| `dispute__finalizedDate` \| `dispute__id` \| `dispute__refusedDate` \| `dispute__resolvedDate` \| `dispute__retractedDate` \| `dispute__state` \| `dispute__timeout` \| `disputed` \| `disputedDate` \| `expired` \| `finalizedDate` \| `id` \| `mutualizerAddress` \| `offer` \| `offer__agentFee` \| `offer__agentId` \| `offer__buyerCancelPenalty` \| `offer__buyerId` \| `offer__collectionIndex` \| `offer__createdAt` \| `offer__creator` \| `offer__disputePeriodDuration` \| `offer__disputeResolverId` \| `offer__id` \| `offer__metadataHash` \| `offer__metadataUri` \| `offer__numberOfCommits` \| `offer__numberOfRedemptions` \| `offer__price` \| `offer__priceType` \| `offer__protocolFee` \| `offer__quantityAvailable` \| `offer__quantityInitial` \| `offer__resolutionPeriodDuration` \| `offer__sellerDeposit` \| `offer__sellerId` \| `offer__validFromDate` \| `offer__validUntilDate` \| `offer__voided` \| `offer__voidedAt` \| `offer__voucherRedeemableFromDate` \| `offer__voucherRedeemableUntilDate` \| `offer__voucherValidDuration` \| `protocolFeeCollected` \| `protocolFeeCollected__amount` \| `protocolFeeCollected__exchangeId` \| `protocolFeeCollected__exchangeToken` \| `protocolFeeCollected__executedBy` \| `protocolFeeCollected__id` \| `redeemedDate` \| `revokedDate` \| `seller` \| `seller__active` \| `seller__admin` \| `seller__assistant` \| `seller__authTokenId` \| `seller__authTokenType` \| `seller__clerk` \| `seller__id` \| `seller__metadataUri` \| `seller__sellerId` \| `seller__treasury` \| `seller__voucherCloneAddress` \| `state` \| `validUntilDate` | no |  |
| `exchangesOrderDirection` | `asc` \| `desc` | no |  |
| `exchangesFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_funds

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_funds

> Reads treasury fund balances for sellers and buyers from the Boson subgraph.

# `get_funds`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads treasury fund balances for sellers and buyers from the Boson subgraph. Supports pagination/ordering/filtering. Read-only — signerAddress not required. Returns: array of &lbrace; tokenAddress, availableAmount, accountId &rbrace;.

**Category:** Funds.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fundsSkip` | number | no |  |
| `fundsFirst` | number | no |  |
| `fundsOrderBy` | `account` \| `accountId` \| `account__createdAt` \| `account__creationTxHash` \| `account__entityId` \| `account__id` \| `account__metadataURI` \| `availableAmount` \| `changes` \| `id` \| `token` \| `tokenAddress` \| `token__address` \| `token__decimals` \| `token__id` \| `token__name` \| `token__symbol` | no |  |
| `fundsOrderDirection` | `asc` \| `desc` | no |  |
| `fundsFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_offers

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_offers

> Reads offer listings from the Boson subgraph.

# `get_offers`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads offer listings from the Boson subgraph. Supports pagination, ordering, and filtering (e.g. by sellerId). Read-only. Returns: array of offers with price, deposit, dates, and quantity.

**Category:** Offer management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offersSkip` | number | no |  |
| `offersFirst` | number | no |  |
| `offersOrderBy` | `agentFee` \| `agentId` \| `buyer` \| `buyerCancelPenalty` \| `buyerId` \| `buyer__active` \| `buyer__id` \| `buyer__wallet` \| `collection` \| `collectionIndex` \| `collection__collectionIndex` \| `collection__externalId` \| `collection__externalIdHash` \| `collection__id` \| `collection__sellerId` \| `condition` \| `condition__gatingType` \| `condition__id` \| `condition__maxCommits` \| `condition__maxTokenId` \| `condition__method` \| `condition__minTokenId` \| `condition__threshold` \| `condition__tokenAddress` \| `condition__tokenType` \| `createdAt` \| `creator` \| `disputePeriodDuration` \| `disputeResolutionTerms` \| `disputeResolutionTerms__buyerEscalationDeposit` \| `disputeResolutionTerms__disputeResolverId` \| `disputeResolutionTerms__escalationResponsePeriod` \| `disputeResolutionTerms__feeAmount` \| `disputeResolutionTerms__id` \| `disputeResolutionTerms__mutualizerAddress` \| `disputeResolver` \| `disputeResolverId` \| `disputeResolver__active` \| `disputeResolver__admin` \| `disputeResolver__assistant` \| `disputeResolver__clerk` \| `disputeResolver__escalationResponsePeriod` \| `disputeResolver__id` \| `disputeResolver__metadataUri` \| `disputeResolver__treasury` \| `exchangeToken` \| `exchangeToken__address` \| `exchangeToken__decimals` \| `exchangeToken__id` \| `exchangeToken__name` \| `exchangeToken__symbol` \| `exchanges` \| `id` \| `metadata` \| `metadataHash` \| `metadataUri` \| `metadata__animationUrl` \| `metadata__condition` \| `metadata__createdAt` \| `metadata__description` \| `metadata__externalUrl` \| `metadata__id` \| `metadata__image` \| `metadata__licenseUrl` \| `metadata__name` \| `metadata__numberOfCommits` \| `metadata__numberOfRedemptions` \| `metadata__quantityAvailable` \| `metadata__schemaUrl` \| `metadata__type` \| `metadata__validFromDate` \| `metadata__validUntilDate` \| `metadata__voided` \| `numberOfCommits` \| `numberOfRedemptions` \| `price` \| `priceType` \| `protocolFee` \| `quantityAvailable` \| `quantityInitial` \| `range` \| `range__end` \| `range__id` \| `range__minted` \| `range__owner` \| `range__start` \| `resolutionPeriodDuration` \| `royaltyInfos` \| `seller` \| `sellerDeposit` \| `sellerId` \| `seller__active` \| `seller__admin` \| `seller__assistant` \| `seller__authTokenId` \| `seller__authTokenType` \| `seller__clerk` \| `seller__id` \| `seller__metadataUri` \| `seller__sellerId` \| `seller__treasury` \| `seller__voucherCloneAddress` \| `validFromDate` \| `validUntilDate` \| `voided` \| `voidedAt` \| `voucherRedeemableFromDate` \| `voucherRedeemableUntilDate` \| `voucherValidDuration` | no |  |
| `offersOrderDirection` | `asc` \| `desc` | no |  |
| `offersFilter` | object | no |  |
| `includeExchanges` | boolean | no |  |
| `exchangesSkip` | number | no |  |
| `exchangesFirst` | number | no |  |
| `exchangesOrderBy` | `buyer` \| `buyer__active` \| `buyer__id` \| `buyer__wallet` \| `cancelledDate` \| `committedDate` \| `completedDate` \| `dispute` \| `disputeResolver` \| `disputeResolver__active` \| `disputeResolver__admin` \| `disputeResolver__assistant` \| `disputeResolver__clerk` \| `disputeResolver__escalationResponsePeriod` \| `disputeResolver__id` \| `disputeResolver__metadataUri` \| `disputeResolver__treasury` \| `dispute__buyerPercent` \| `dispute__decidedDate` \| `dispute__disputedDate` \| `dispute__escalatedDate` \| `dispute__exchangeId` \| `dispute__finalizedDate` \| `dispute__id` \| `dispute__refusedDate` \| `dispute__resolvedDate` \| `dispute__retractedDate` \| `dispute__state` \| `dispute__timeout` \| `disputed` \| `disputedDate` \| `expired` \| `finalizedDate` \| `id` \| `mutualizerAddress` \| `offer` \| `offer__agentFee` \| `offer__agentId` \| `offer__buyerCancelPenalty` \| `offer__buyerId` \| `offer__collectionIndex` \| `offer__createdAt` \| `offer__creator` \| `offer__disputePeriodDuration` \| `offer__disputeResolverId` \| `offer__id` \| `offer__metadataHash` \| `offer__metadataUri` \| `offer__numberOfCommits` \| `offer__numberOfRedemptions` \| `offer__price` \| `offer__priceType` \| `offer__protocolFee` \| `offer__quantityAvailable` \| `offer__quantityInitial` \| `offer__resolutionPeriodDuration` \| `offer__sellerDeposit` \| `offer__sellerId` \| `offer__validFromDate` \| `offer__validUntilDate` \| `offer__voided` \| `offer__voidedAt` \| `offer__voucherRedeemableFromDate` \| `offer__voucherRedeemableUntilDate` \| `offer__voucherValidDuration` \| `protocolFeeCollected` \| `protocolFeeCollected__amount` \| `protocolFeeCollected__exchangeId` \| `protocolFeeCollected__exchangeToken` \| `protocolFeeCollected__executedBy` \| `protocolFeeCollected__id` \| `redeemedDate` \| `revokedDate` \| `seller` \| `seller__active` \| `seller__admin` \| `seller__assistant` \| `seller__authTokenId` \| `seller__authTokenType` \| `seller__clerk` \| `seller__id` \| `seller__metadataUri` \| `seller__sellerId` \| `seller__treasury` \| `seller__voucherCloneAddress` \| `state` \| `validUntilDate` | no |  |
| `exchangesOrderDirection` | `asc` \| `desc` | no |  |
| `exchangesFilter` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_registered_agents

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_registered_agents

> Returns all dACP agents registered with this MCP server instance, with their associated protocol entities and roles.

# `get_registered_agents`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Returns all dACP agents registered with this MCP server instance, with their associated protocol entities and roles. No auth required.

**Category:** Agent registry.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_sellers

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_sellers

> Reads seller account entities from the Boson subgraph.

# `get_sellers`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads seller account entities from the Boson subgraph. Optionally includes related offers, exchanges, funds, and logs. Read-only. Returns: array of seller entities with addresses and metadataUri.

**Category:** Seller & buyer.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sellersSkip` | number | no |  |
| `sellersFirst` | number | no |  |
| `sellersOrderBy` | `active` \| `admin` \| `assistant` \| `authTokenId` \| `authTokenType` \| `clerk` \| `collections` \| `exchanges` \| `funds` \| `id` \| `logs` \| `metadata` \| `metadataUri` \| `metadata__contactPreference` \| `metadata__createdAt` \| `metadata__description` \| `metadata__id` \| `metadata__kind` \| `metadata__legalTradingName` \| `metadata__name` \| `metadata__type` \| `metadata__website` \| `offers` \| `pendingSeller` \| `pendingSeller__admin` \| `pendingSeller__assistant` \| `pendingSeller__authTokenId` \| `pendingSeller__authTokenType` \| `pendingSeller__clerk` \| `pendingSeller__id` \| `pendingSeller__metadataUri` \| `royaltyRecipients` \| `sellerId` \| `treasury` \| `voucherCloneAddress` | no |  |
| `sellersOrderDirection` | `asc` \| `desc` | no |  |
| `sellersFilter` | object | no |  |
| `includeExchanges` | boolean | no |  |
| `includeOffers` | boolean | no |  |
| `includeFunds` | boolean | no |  |
| `includeLogs` | boolean | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_sellers_by_address

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_sellers_by_address

> Reads seller entities associated with a specific Ethereum address.

# `get_sellers_by_address`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Reads seller entities associated with a specific Ethereum address. Use this to check if signerAddress already has a seller account before calling create_seller. Read-only. Returns: array of seller entities.

**Category:** Seller & buyer.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | yes |  |
| `sellersSkip` | number | no |  |
| `sellersFirst` | number | no |  |
| `sellersOrderBy` | `active` \| `admin` \| `assistant` \| `authTokenId` \| `authTokenType` \| `clerk` \| `collections` \| `exchanges` \| `funds` \| `id` \| `logs` \| `metadata` \| `metadataUri` \| `metadata__contactPreference` \| `metadata__createdAt` \| `metadata__description` \| `metadata__id` \| `metadata__kind` \| `metadata__legalTradingName` \| `metadata__name` \| `metadata__type` \| `metadata__website` \| `offers` \| `pendingSeller` \| `pendingSeller__admin` \| `pendingSeller__assistant` \| `pendingSeller__authTokenId` \| `pendingSeller__authTokenType` \| `pendingSeller__clerk` \| `pendingSeller__id` \| `pendingSeller__metadataUri` \| `royaltyRecipients` \| `sellerId` \| `treasury` \| `voucherCloneAddress` | no |  |
| `sellersOrderDirection` | `asc` \| `desc` | no |  |
| `sellersFilter` | object | no |  |
| `includeExchanges` | boolean | no |  |
| `includeOffers` | boolean | no |  |
| `includeFunds` | boolean | no |  |
| `includeLogs` | boolean | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# get_supported_tokens

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/get_supported_tokens

> Returns ERC-20 tokens accepted as exchange tokens on the given configId deployment.

# `get_supported_tokens`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Returns ERC-20 tokens accepted as exchange tokens on the given configId deployment. Use returned addresses in exchangeTokenAddress fields of create_offer. Read-only. Returns: array of &lbrace; address, name, symbol, decimals &rbrace;.

**Category:** Configuration.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# raise_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/raise_dispute

> Raises a dispute on a redeemed exchange.

# `raise_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Raises a dispute on a redeemed exchange. Caller must be the buyer. Must be called within disputePeriodDurationInMS after redemption. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# redeem_voucher

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/redeem_voucher

> Redeems a voucher, signalling physical receipt of goods and starting the dispute period clock.

# `redeem_voucher`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Redeems a voucher, signalling physical receipt of goods and starting the dispute period clock. Caller must be the buyer. After redemption, buyer has disputePeriodDurationInMS to raise a dispute. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# refuse_escalated_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/refuse_escalated_dispute

> Dispute resolver refuses to decide an escalated dispute.

# `refuse_escalated_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Dispute resolver refuses to decide an escalated dispute. Returns the escalation fee to the buyer and resets dispute to 'Resolving' state. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# register_agent

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/register_agent

> Registers a dACP agent with this MCP server instance, associating its Ethereum identities and roles.

# `register_agent`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Registers a dACP agent with this MCP server instance, associating its Ethereum identities and roles. The signature proves control of each signerAddress. Server-local state — no configId/signerAddress context needed. Returns: registration confirmation.

**Category:** Agent registry.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `entities` | object[] | yes |  |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# render_contractual_agreement

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/render_contractual_agreement

> Renders the legal contractual agreement text/HTML for an offer using its offer data and metadata.

# `render_contractual_agreement`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Renders the legal contractual agreement text/HTML for an offer using its offer data and metadata. Use to preview or store the agreement. Returns: rendered agreement string.

**Category:** Offer management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `template` | string | yes |  |
| `offerData` | object | yes |  |
| `offerMetadata` | object | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# resolve_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/resolve_dispute

> Resolves a dispute by mutual agreement.

# `resolve_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Resolves a dispute by mutual agreement. Workflow: (1) create_dispute_resolution_proposal generates typed data, (2) both parties sign the typed data locally with their wallet (EIP-712), (3) either party submits sigR/sigS/sigV here. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `buyerPercentBasisPoints` | — | yes | Agreed buyer share in basis points (0–10000). Both parties must sign the same value. Obtain via create_dispute_resolution_proposal then sign the typed data locally with each party's wallet (EIP-712). |
| `sigR` | string | yes | 32-byte R component of the ECDSA resolution signature as 0x-prefixed hex. From the locally-signed EIP-712 signature parameters. |
| `sigS` | string | yes | 32-byte S component as 0x-prefixed hex. From the locally-signed EIP-712 signature parameters. |
| `sigV` | — | yes | Recovery byte V: 27 or 28. From the locally-signed EIP-712 signature parameters. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# retract_dispute

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/retract_dispute

> Retracts a raised dispute, releasing seller deposit and restoring completion flow.

# `retract_dispute`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Retracts a raised dispute, releasing seller deposit and restoring completion flow. Caller must be the buyer who raised it. Returns unsigned transaction data.

**Category:** Dispute management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# revoke_voucher

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/revoke_voucher

> Revokes a committed (not yet redeemed) voucher on behalf of the seller, returning funds to the buyer.

# `revoke_voucher`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Revokes a committed (not yet redeemed) voucher on behalf of the seller, returning funds to the buyer. Caller must be the seller assistant. Returns unsigned transaction data.

**Category:** Exchange management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `exchangeId` | string | yes | Numeric ID of the exchange/dispute to act on. Obtain from get_exchanges or the response of commit_to_offer. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# send_forwarded_meta_transaction

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/send_forwarded_meta_transaction

> Relays a Biconomy forwarded meta-transaction (ERC-20 gas payment).

# `send_forwarded_meta_transaction`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Relays a Biconomy forwarded meta-transaction (ERC-20 gas payment). Requires a complete ERC20ForwardRequest and domain separator signature. Returns: relay transaction data.

**Category:** Meta-transactions & broadcast.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contractAddress` | string | yes | Valid Ethereum address (e.g. '0xAbCd...' or '0xabcd...'). Mixed-case addresses are checksum-validated; all-lowercase and all-uppercase addresses are also accepted. |
| `request` | object | yes |  |
| `domainSeparator` | string | yes |  |
| `signature` | string | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# send_meta_transaction

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/send_meta_transaction

> Relays a pre-signed meta-transaction via Biconomy so the user pays no gas.

# `send_meta_transaction`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Relays a pre-signed meta-transaction via Biconomy so the user pays no gas. Requires sigR/sigS/sigV from a locally-signed EIP-712 payload. Use when the target operation requires metaTx relay. Returns: relay transaction data.

**Category:** Meta-transactions & broadcast.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `functionName` | string | yes |  |
| `functionSignature` | string | yes |  |
| `nonce` | string \| number | yes |  |
| `sigR` | string | yes |  |
| `sigS` | string | yes |  |
| `sigV` | string \| number | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# send_native_meta_transaction

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/send_native_meta_transaction

> Relays a native meta-transaction (EIP-712 signed function call) via Biconomy.

# `send_native_meta_transaction`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Relays a native meta-transaction (EIP-712 signed function call) via Biconomy. Requires ABI-encoded function signature and sigR/sigS/sigV from a locally-signed EIP-712 payload. Returns: relay transaction data.

**Category:** Meta-transactions & broadcast.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contractAddress` | string | yes | Valid Ethereum address (e.g. '0xAbCd...' or '0xabcd...'). Mixed-case addresses are checksum-validated; all-lowercase and all-uppercase addresses are also accepted. |
| `functionSignature` | string | yes |  |
| `sigR` | string | yes |  |
| `sigS` | string | yes |  |
| `sigV` | string \| number | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# send_signed_transaction

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/send_signed_transaction

> Broadcasts a signed raw Ethereum transaction to the network.

# `send_signed_transaction`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Broadcasts a signed raw Ethereum transaction to the network. signedTransaction must be 0x-prefixed RLP-encoded hex obtained from local wallet signing (e.g. ethers `wallet.signTransaction(tx)`). Returns: transaction hash, block number, and gas used.

**Category:** Meta-transactions & broadcast.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `signedTransaction` | string | yes | RLP-encoded signed Ethereum transaction as 0x-prefixed hex string. Obtain from local wallet signing (e.g. ethers `wallet.signTransaction(tx)`). |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# sign_full_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/sign_full_offer

> Generates EIP-712 typed data for a non-listed (private) offer that the offer creator must sign.

# `sign_full_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Generates EIP-712 typed data for a non-listed (private) offer that the offer creator must sign. Call before create_offer_and_commit or void_non_listed_offer. Returns: typed data structure — sign it locally with your wallet (EIP-712), then use the signature in the next step.

**Category:** Offer management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offerCreator` | string | yes | Ethereum address of the seller creating this non-listed offer. Must match the seller's assistant address. |
| `committer` | — | yes | Ethereum address of the buyer committing in the same transaction. |
| `collectionIndex` | string | no | Index of the seller's NFT collection for vouchers. Omit to use default (index 0). |
| `royaltyInfo` | object | no |  |
| `drMutualizerAddress` | — | no | Optional dispute resolver mutualizer contract address that pools resolution funds. |
| `conditionalTokenId` | — | no | Optional token ID of the NFT gate token used by this specific commit (for SpecificToken gating type). |
| `condition` | object | no |  |
| `useDepositedFunds` | boolean | no | If true, use funds already deposited in the protocol treasury instead of transferring from the wallet. |
| `sellerId` | — | yes | Numeric ID of the seller entity. Obtain via get_sellers_by_address. |
| `buyerId` | — | yes | Numeric ID of the buyer entity. Use '0' for seller-initiated offers. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `metadataUri` | string | yes | IPFS URI pointing to the offer metadata JSON. Obtain by calling store_product_v1_metadata, store_bundle_metadata, or store_base_metadata. |
| `metadataHash` | string | yes | Keccak256 hash of the metadata JSON. Returned alongside metadataUri from the store_*_metadata tools. |
| `exchangeTokenAddress` | — | no | ERC-20 token accepted for payment. Omit or use address(0) for native ETH. Call get_supported_tokens for valid values. |
| `price` | — | yes | Offer price in the exchange token's smallest unit (wei). Pass as string to avoid precision loss, e.g. '1000000000000000000' = 1 ETH. |
| `sellerDeposit` | — | yes | Seller collateral in same unit as price. Released to seller on completion or forfeited on dispute. Pass as string. |
| `agentId` | — | no | Optional dACP agent facilitating this offer. Omit or pass '0' if no agent. |
| `buyerCancellationPenalty` | — | yes | Amount buyer forfeits on cancel, in same unit as price. Must be &lt;= price. Pass as string. |
| `quantityAvailable` | number | yes | How many times this offer can be committed to. Must be 1 when creator='BUYER'. |
| `validFromDateInMS` | number | yes | Unix timestamp in milliseconds when the offer becomes active. Example: Date.now() for immediate. |
| `validUntilDateInMS` | number | yes | Unix timestamp in milliseconds when the offer can no longer be committed to. |
| `voucherRedeemableFromDateInMS` | number | yes | Timestamp in ms from which buyer can redeem. Must be &gt;= validFromDateInMS. |
| `voucherRedeemableUntilDateInMS` | number | yes | Timestamp in ms after which voucher cannot be redeemed. Set to 0 to use voucherValidDurationInMS instead. |
| `disputePeriodDurationInMS` | number | yes | Duration in ms for buyer to raise a dispute after redeeming. Example: 604800000 = 7 days. |
| `voucherValidDurationInMS` | number | yes | Voucher is redeemable for this many ms after commit. Set to 0 to use voucherRedeemableUntilDateInMS instead. |
| `resolutionPeriodDurationInMS` | number | yes | Duration in ms to respond to a resolution proposal before it expires. Example: 259200000 = 3 days. |
| `disputeResolverId` | string | no | ID of the dispute resolver for escalated disputes. Call get_dispute_resolvers to list available resolvers. |
| `feeLimit` | — | no | Max protocol fee the seller accepts in same token unit. Pass as string. |
| `priceType` | number | no | 0 = static price, 1 = discovery price (auction). |
| `creator` | `SELLER` \| `BUYER` | no | 'SELLER' (default) = seller creates offer. 'BUYER' = buyer-initiated offer, quantity must be 1. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# store_base_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/store_base_metadata

> Stores a Base metadata object to IPFS.

# `store_base_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Stores a Base metadata object to IPFS. Use for simple offers that don't require ProductV1 or Bundle structure. Returns: &lbrace; metadataUri, metadataHash &rbrace; for use in create_offer.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `BASE` | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `condition` | string | no |  |
| `animationUrl` | string | no |  |
| `youtubeUrl` | string | no |  |
| `attributes` | object[] | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# store_bundle_item_nft_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/store_bundle_item_nft_metadata

> Stores a single NFT bundle item's metadata to IPFS.

# `store_bundle_item_nft_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Stores a single NFT bundle item's metadata to IPFS. Call once per NFT component in a bundle before store_bundle_metadata. Returns: &lbrace; url: 'ipfs://...' &rbrace; to include in the items array.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `ITEM_NFT` | yes |  |
| `name` | string | yes |  |
| `description` | string | no |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | no |  |
| `animationUrl` | string | no |  |
| `youtubeUrl` | string | no |  |
| `image_data` | string | no |  |
| `external_url` | string | no |  |
| `animation_url` | string | no |  |
| `youtube_url` | string | no |  |
| `attributes` | object[] | no |  |
| `chainId` | number | no |  |
| `contract` | string | no |  |
| `tokenId` | string | no |  |
| `tokenIdRange` | object | no |  |
| `terms` | object[] | no |  |
| `quantity` | number | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# store_bundle_item_product_v1_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/store_bundle_item_product_v1_metadata

> Stores a single ProductV1 bundle item's metadata to IPFS.

# `store_bundle_item_product_v1_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Stores a single ProductV1 bundle item's metadata to IPFS. Call once per physical product in a bundle before store_bundle_metadata. Returns: &lbrace; url: 'ipfs://...' &rbrace; to include in the items array.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `ITEM_PRODUCT_V1` | yes |  |
| `uuid` | string | yes |  |
| `product` | object | yes |  |
| `variations` | object[] | no |  |
| `shipping` | object | yes |  |
| `exchangePolicy` | object | yes |  |
| `productOverrides` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# store_bundle_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/store_bundle_metadata

> Stores a Bundle metadata object to IPFS.

# `store_bundle_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Stores a Bundle metadata object to IPFS. Prerequisite: call store_bundle_item_product_v1_metadata and/or store_bundle_item_nft_metadata first; include their returned URLs in the items array. Returns: &lbrace; metadataUri, metadataHash &rbrace;.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `BUNDLE` | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `youtubeUrl` | string | no |  |
| `condition` | string | no |  |
| `animationUrl` | string | no |  |
| `attributes` | object[] | no |  |
| `bundleUuid` | string | yes |  |
| `seller` | object | yes |  |
| `items` | object[] | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# store_product_v1_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/store_product_v1_metadata

> Stores a ProductV1 metadata object to IPFS.

# `store_product_v1_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Stores a ProductV1 metadata object to IPFS. Call before create_offer to get metadataUri and metadataHash. Returns: &lbrace; metadataUri: 'ipfs://...', metadataHash: '0x...' &rbrace;.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `PRODUCT_V1` | yes |  |
| `uuid` | string | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `youtubeUrl` | string | no |  |
| `condition` | string | no |  |
| `image` | string | yes |  |
| `imageData` | string | no |  |
| `animationUrl` | string | no |  |
| `attributes` | object[] | yes |  |
| `product` | object | yes |  |
| `variations` | object[] | no |  |
| `seller` | object | yes |  |
| `shipping` | object | yes |  |
| `exchangePolicy` | object | yes |  |
| `productOverrides` | object | no |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# update_seller

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/update_seller

> Updates an existing seller account.

# `update_seller`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Updates an existing seller account. Caller must be the current seller admin (signerAddress). Use get_sellers_by_address to retrieve the seller id first. Returns unsigned transaction data.

**Category:** Seller & buyer.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `type` | string | yes |  |
| `name` | string | no |  |
| `description` | string | no |  |
| `legalTradingName` | string | no |  |
| `kind` | string | yes |  |
| `website` | string | no |  |
| `images` | object[] | no |  |
| `contactLinks` | object[] | no |  |
| `contactPreference` | string | yes |  |
| `socialLinks` | object[] | no |  |
| `salesChannels` | object[] | no |  |
| `authTokenId` | string | yes | NFT token ID used as auth token (e.g. Lens profile ID). Pass '0' if not using auth tokens. |
| `authTokenType` | number | yes | Auth token type: 0=None, 1=Lens Protocol profile NFT. |
| `id` | — | yes | Numeric ID of the existing seller entity to update. Obtain from get_sellers_by_address. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# validate_metadata

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/validate_metadata

> Validates a metadata object against the Boson Protocol schema (PRODUCT_V1, BUNDLE, BASE, etc.) without storing it.

# `validate_metadata`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Validates a metadata object against the Boson Protocol schema (PRODUCT_V1, BUNDLE, BASE, etc.) without storing it. Use before store_*_metadata to catch errors early. Read-only. Returns: validation result with any errors.

**Category:** Offer management.
**Returns unsigned tx?** No — read-only or returns signed payload.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | yes |  |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# void_non_listed_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/void_non_listed_offer

> Voids a private (non-listed) offer before it is fulfilled.

# `void_non_listed_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Voids a private (non-listed) offer before it is fulfilled. Prerequisite: call sign_full_offer and sign the returned typed data locally with your wallet (EIP-712) to obtain the signature. Returns unsigned transaction data.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `condition` | object | no |  |
| `useDepositedFunds` | boolean | no | If true, use funds already deposited in the protocol treasury instead of transferring from the wallet. |
| `sellerId` | — | yes | Numeric ID of the seller entity. Obtain via get_sellers_by_address. |
| `buyerId` | — | yes | Numeric ID of the buyer entity. Use '0' for seller-initiated offers. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |
| `metadataUri` | string | yes | IPFS URI pointing to the offer metadata JSON. Obtain by calling store_product_v1_metadata, store_bundle_metadata, or store_base_metadata. |
| `metadataHash` | string | yes | Keccak256 hash of the metadata JSON. Returned alongside metadataUri from the store_*_metadata tools. |
| `exchangeTokenAddress` | — | no | ERC-20 token accepted for payment. Omit or use address(0) for native ETH. Call get_supported_tokens for valid values. |
| `price` | — | yes | Offer price in the exchange token's smallest unit (wei). Pass as string to avoid precision loss, e.g. '1000000000000000000' = 1 ETH. |
| `sellerDeposit` | — | yes | Seller collateral in same unit as price. Released to seller on completion or forfeited on dispute. Pass as string. |
| `agentId` | — | no | Optional dACP agent facilitating this offer. Omit or pass '0' if no agent. |
| `buyerCancellationPenalty` | — | yes | Amount buyer forfeits on cancel, in same unit as price. Must be &lt;= price. Pass as string. |
| `quantityAvailable` | number | yes | How many times this offer can be committed to. Must be 1 when creator='BUYER'. |
| `validFromDateInMS` | number | yes | Unix timestamp in milliseconds when the offer becomes active. Example: Date.now() for immediate. |
| `validUntilDateInMS` | number | yes | Unix timestamp in milliseconds when the offer can no longer be committed to. |
| `voucherRedeemableFromDateInMS` | number | yes | Timestamp in ms from which buyer can redeem. Must be &gt;= validFromDateInMS. |
| `voucherRedeemableUntilDateInMS` | number | yes | Timestamp in ms after which voucher cannot be redeemed. Set to 0 to use voucherValidDurationInMS instead. |
| `disputePeriodDurationInMS` | number | yes | Duration in ms for buyer to raise a dispute after redeeming. Example: 604800000 = 7 days. |
| `voucherValidDurationInMS` | number | yes | Voucher is redeemable for this many ms after commit. Set to 0 to use voucherRedeemableUntilDateInMS instead. |
| `resolutionPeriodDurationInMS` | number | yes | Duration in ms to respond to a resolution proposal before it expires. Example: 259200000 = 3 days. |
| `disputeResolverId` | string | no | ID of the dispute resolver for escalated disputes. Call get_dispute_resolvers to list available resolvers. |
| `collectionIndex` | — | no | Index of the seller's NFT collection for vouchers. Omit to use default (index 0). |
| `feeLimit` | — | no | Max protocol fee the seller accepts in same token unit. Pass as string. |
| `priceType` | number | no | 0 = static price, 1 = discovery price (auction). |
| `royaltyInfo` | object | no |  |
| `creator` | `SELLER` \| `BUYER` | no | 'SELLER' (default) = seller creates offer. 'BUYER' = buyer-initiated offer, quantity must be 1. |
| `drMutualizerAddress` | — | no | Optional dispute resolver mutualizer contract address that pools resolution funds. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# void_non_listed_offer_batch

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/void_non_listed_offer_batch

> Voids multiple private offers atomically.

# `void_non_listed_offer_batch`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Voids multiple private offers atomically. Same prerequisite as void_non_listed_offer, but for an array of full offer objects. Returns unsigned transaction data.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fullOffers` | object[] | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# void_offer

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/void_offer

> Voids a listed offer so it can no longer be committed to.

# `void_offer`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Voids a listed offer so it can no longer be committed to. Caller must be the seller assistant. Existing exchanges are unaffected. Returns unsigned transaction data.

**Category:** Offer management.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offerId` | string | yes | ID of the listed offer to void. Caller must be the seller assistant. Existing exchanges are unaffected. |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | string | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# withdraw_funds

URL: https://www.bosonprotocol.io/docs/reference/mcp-tools/withdraw_funds

> Withdraws funds from an entity's protocol treasury to the entity's treasury address.

# `withdraw_funds`

:::info
**Generated from `agentic-commerce` MCP tools/list against `https://mcp-staging.bosonprotocol.io/mcp`. Edit the zod schema in the source repo, not this page.**
:::

Withdraws funds from an entity's protocol treasury to the entity's treasury address. Sellers withdraw proceeds; buyers withdraw refunds. Caller must control the entity via signerAddress. Returns unsigned transaction data.

**Category:** Funds.
**Returns unsigned tx?** Likely yes — sign locally and broadcast via `send_signed_transaction` or a meta-tx relay.

## Input schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityId` | string | yes | Numeric ID of the seller or buyer entity withdrawing funds. |
| `list` | object[] | yes |  |
| `configId` | string | yes | Boson/Fermion Protocol deployment identifier. Format: '&lt;env&gt;-&lt;chainId&gt;-&lt;index&gt;' e.g. 'production-137-0' (Polygon mainnet), 'testing-80002-0' (Amoy testnet). Call get_config_ids to list all valid values for this server. |
| `signerAddress` | — | yes | Ethereum address that will sign and send this transaction. Must match the wallet that will sign the returned transaction locally. |
| `executionMode` | `direct` \| `metaTx` | no | 'direct' = standard on-chain tx (sign locally with your wallet → send_signed_transaction). 'metaTx' = gasless relay via Biconomy (send_meta_transaction). Defaults to 'direct'. |


## Related

- [Reference → MCP tools](/reference/mcp-tools) — full catalogue.
- [Build for AI agents → The 3-step signing pattern](/agents/signing) — what to do with returned unsigned transactions.
- [Concepts → Signing & meta-transactions](/concepts/signing) — canonical signing reference.

---

# Reference — Metadata schemas

URL: https://www.bosonprotocol.io/docs/reference/metadata

> PRODUCT_V1, BUNDLE, BASE, and the rest of the @bosonprotocol/metadata JSON Schemas.

# Metadata schemas

:::info
**Generated from `@bosonprotocol/metadata` schema.json files. Edit the schemas in the source repo, not this page.**
:::

Each Boson offer (and the seller / collection / voucher entities around it) carries an off-chain metadata document pinned to IPFS, with its content hash stored on-chain. The schemas below define those documents.

`@bosonprotocol/metadata` wraps each schema with [yup](https://github.com/jquense/yup) (via [schema-to-yup](https://github.com/kristianmandrup/schema-to-yup)) and exposes a validator per type. The JSON Schema is the source of truth.

## Helpers

```ts twoslash
// @noErrors
import {
  productV1MetadataSchema,
  bundleMetadataSchema,
  validateMetadata,
  createVariantProductMetadata,
} from "@bosonprotocol/metadata"

// There are no `*MetadataFactory()` helpers — construct the metadata object
// directly against the schema's required fields. `validateMetadata` (Yup)
// raises if anything is missing.
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "PRODUCT_V1" as const,
  uuid: crypto.randomUUID(),
  // …all other required fields…
}
validateMetadata(metadata as any)  // throws on invalid; no return value
```

For PRODUCT_V1 offers with variants (e.g. multiple sizes), use `createVariantProductMetadata(baseMetadata, variants)` — that's the only metadata-building helper exported by the package.

## `BASE`

_Source: [`packages/metadata/src/base/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/base/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"BASE"` | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `condition` | string | no |  |
| `animationUrl` | string | no |  |
| `youtubeUrl` | string | no |  |
| `attributes` | object[] — see [attributes\[\]](#attributes-item) | no |  |

### `attributes[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `traitType` | string | yes |  |
| `value` | string | yes |  |
| `displayType` | string | no |  |

## `PRODUCT_V1`

_Source: [`packages/metadata/src/product-v1/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/product-v1/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"PRODUCT_V1"` | yes |  |
| `uuid` | string | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `youtubeUrl` | string | no |  |
| `condition` | string | no |  |
| `image` | string | yes |  |
| `imageData` | string | no |  |
| `animationUrl` | string | no |  |
| `attributes` | object[] — see [attributes\[\]](#attributes-item) | yes |  |
| `product` | object — see [product](#product) | yes |  |
| `variations` | object[] — see [variations\[\]](#variations-item) | no |  |
| `seller` | object — see [seller](#seller) | yes |  |
| `shipping` | object — see [shipping](#shipping) | yes |  |
| `exchangePolicy` | object — see [exchangePolicy](#exchangepolicy) | yes |  |
| `productOverrides` | object — see [productOverrides](#productoverrides) | no |  |

### `attributes[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `traitType` | string | yes |  |
| `value` | string | yes |  |
| `displayType` | string | no |  |

### `product`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | yes |  |
| `version` | number | yes |  |
| `title` | string | yes |  |
| `description` | string | yes |  |
| `identification_sKU` | string | no |  |
| `identification_productId` | string | no |  |
| `identification_productIdType` | string | no |  |
| `productionInformation_brandName` | string | yes |  |
| `productionInformation_manufacturer` | string | no |  |
| `productionInformation_manufacturerPartNumber` | string | no |  |
| `productionInformation_modelNumber` | string | no |  |
| `productionInformation_materials` | string[] | no |  |
| `details_category` | string | no |  |
| `details_subCategory` | string | no |  |
| `details_subCategory2` | string | no |  |
| `details_offerCategory` | `"PHYSICAL"` \| `"PHYGITAL"` \| `"DIGITAL"` | yes |  |
| `details_tags` | string[] | no |  |
| `details_sections` | string[] | no |  |
| `details_personalisation` | string[] | no |  |
| `visuals_images` | object[] — see [product.visuals_images\[\]](#product-visuals-images-item) | yes |  |
| `visuals_videos` | object[] — see [product.visuals_videos\[\]](#product-visuals-videos-item) | no |  |

### `variations[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes |  |
| `option` | string | yes |  |

### `seller`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultVersion` | number | yes |  |
| `name` | string | yes |  |
| `description` | string | no |  |
| `externalUrl` | string | no |  |
| `tokenId` | string | no |  |
| `images` | object[] — see [seller.images\[\]](#seller-images-item) | no |  |
| `contactLinks` | object[] — see [seller.contactLinks\[\]](#seller-contactlinks-item) | yes |  |

### `shipping`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultVersion` | number | no |  |
| `countryOfOrigin` | string | no |  |
| `supportedJurisdictions` | object[] — see [shipping.supportedJurisdictions\[\]](#shipping-supportedjurisdictions-item) | no |  |
| `redemptionPoint` | string | no |  |
| `returnPeriod` | string | yes |  |

### `exchangePolicy`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | yes |  |
| `version` | number | yes |  |
| `label` | string | no |  |
| `template` | string | yes |  |
| `sellerContactMethod` | string | yes |  |
| `disputeResolverContactMethod` | string | yes |  |

### `productOverrides`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no |  |
| `description` | string | no |  |
| `identification_sKU` | string | no |  |
| `identification_productId` | string | no |  |
| `identification_productIdType` | string | no |  |
| `productionInformation_brandName` | string | no |  |
| `productionInformation_manufacturer` | string | no |  |
| `productionInformation_manufacturerPartNumber` | string | no |  |
| `productionInformation_modelNumber` | string | no |  |
| `productionInformation_materials` | string[] | no |  |
| `visuals_images` | object[] — see [productOverrides.visuals_images\[\]](#productoverrides-visuals-images-item) | no |  |
| `visuals_videos` | object[] — see [productOverrides.visuals_videos\[\]](#productoverrides-visuals-videos-item) | no |  |

### `product.visuals_images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `product.visuals_videos[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `seller.images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `seller.contactLinks[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | yes |  |

### `shipping.supportedJurisdictions[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes |  |
| `deliveryTime` | string | yes |  |

### `productOverrides.visuals_images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `productOverrides.visuals_videos[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

## `BUNDLE`

_Source: [`packages/metadata/src/bundle/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/bundle/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"BUNDLE"` | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `youtubeUrl` | string | no |  |
| `condition` | string | no |  |
| `animationUrl` | string | no |  |
| `attributes` | object[] — see [attributes\[\]](#attributes-item) | no |  |
| `bundleUuid` | string | yes |  |
| `seller` | object — see [seller](#seller) | yes |  |
| `items` | object[] — see [items\[\]](#items-item) | yes |  |

### `attributes[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `traitType` | string | yes |  |
| `value` | string | yes |  |
| `displayType` | string | no |  |

### `seller`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultVersion` | number | yes |  |
| `name` | string | yes |  |
| `description` | string | no |  |
| `externalUrl` | string | no |  |
| `tokenId` | string | no |  |
| `images` | object[] — see [seller.images\[\]](#seller-images-item) | no |  |
| `contactLinks` | object[] — see [seller.contactLinks\[\]](#seller-contactlinks-item) | yes |  |

### `items[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |

### `seller.images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `seller.contactLinks[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | yes |  |

## `ProductV1 bundle item`

_Source: [`packages/metadata/src/productV1Item/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/productV1Item/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"ITEM_PRODUCT_V1"` | yes |  |
| `uuid` | string | yes |  |
| `product` | object — see [product](#product) | yes |  |
| `variations` | object[] — see [variations\[\]](#variations-item) | no |  |
| `shipping` | object — see [shipping](#shipping) | yes |  |
| `exchangePolicy` | object — see [exchangePolicy](#exchangepolicy) | yes |  |
| `productOverrides` | object — see [productOverrides](#productoverrides) | no |  |

### `product`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | yes |  |
| `version` | number | yes |  |
| `title` | string | yes |  |
| `description` | string | yes |  |
| `identification_sKU` | string | no |  |
| `identification_productId` | string | no |  |
| `identification_productIdType` | string | no |  |
| `productionInformation_brandName` | string | yes |  |
| `productionInformation_manufacturer` | string | no |  |
| `productionInformation_manufacturerPartNumber` | string | no |  |
| `productionInformation_modelNumber` | string | no |  |
| `productionInformation_materials` | string[] | no |  |
| `details_category` | string | no |  |
| `details_subCategory` | string | no |  |
| `details_subCategory2` | string | no |  |
| `details_offerCategory` | `"PHYSICAL"` \| `"PHYGITAL"` \| `"DIGITAL"` | yes |  |
| `details_tags` | string[] | no |  |
| `details_sections` | string[] | no |  |
| `details_personalisation` | string[] | no |  |
| `visuals_images` | object[] — see [product.visuals_images\[\]](#product-visuals-images-item) | yes |  |
| `visuals_videos` | object[] — see [product.visuals_videos\[\]](#product-visuals-videos-item) | no |  |

### `variations[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes |  |
| `option` | string | yes |  |

### `shipping`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultVersion` | number | no |  |
| `countryOfOrigin` | string | no |  |
| `supportedJurisdictions` | object[] — see [shipping.supportedJurisdictions\[\]](#shipping-supportedjurisdictions-item) | no |  |
| `redemptionPoint` | string | no |  |
| `returnPeriod` | string | yes |  |

### `exchangePolicy`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | yes |  |
| `version` | number | yes |  |
| `label` | string | no |  |
| `template` | string | yes |  |
| `sellerContactMethod` | string | yes |  |
| `disputeResolverContactMethod` | string | yes |  |

### `productOverrides`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no |  |
| `description` | string | no |  |
| `identification_sKU` | string | no |  |
| `identification_productId` | string | no |  |
| `identification_productIdType` | string | no |  |
| `productionInformation_brandName` | string | no |  |
| `productionInformation_manufacturer` | string | no |  |
| `productionInformation_manufacturerPartNumber` | string | no |  |
| `productionInformation_modelNumber` | string | no |  |
| `productionInformation_materials` | string[] | no |  |
| `visuals_images` | object[] — see [productOverrides.visuals_images\[\]](#productoverrides-visuals-images-item) | no |  |
| `visuals_videos` | object[] — see [productOverrides.visuals_videos\[\]](#productoverrides-visuals-videos-item) | no |  |

### `product.visuals_images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `product.visuals_videos[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `shipping.supportedJurisdictions[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes |  |
| `deliveryTime` | string | yes |  |

### `productOverrides.visuals_images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

### `productOverrides.visuals_videos[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |

## `NFT bundle item`

_Source: [`packages/metadata/src/nftItem/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/nftItem/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"ITEM_NFT"` | yes |  |
| `name` | string | yes |  |
| `description` | string | no |  |
| `image` | string | no |  |
| `imageData` | string | no |  |
| `externalUrl` | string | no |  |
| `animationUrl` | string | no |  |
| `youtubeUrl` | string | no |  |
| `image_data` | string | no |  |
| `external_url` | string | no |  |
| `animation_url` | string | no |  |
| `youtube_url` | string | no |  |
| `attributes` | object[] — see [attributes\[\]](#attributes-item) | no |  |
| `chainId` | number | no |  |
| `contract` | string | no |  |
| `tokenId` | string | no |  |
| `tokenIdRange` | object — see [tokenIdRange](#tokenidrange) | no |  |
| `terms` | object[] — see [terms\[\]](#terms-item) | no |  |
| `quantity` | number | no |  |

### `attributes[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `traitType` | string | no |  |
| `trait_type` | string | no |  |
| `value` | string | yes |  |
| `displayType` | string | no |  |
| `display_type` | string | no |  |

### `tokenIdRange`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | string | no |  |
| `max` | string | no |  |

### `terms[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes |  |
| `value` | string | yes |  |
| `displayKey` | string | no |  |

## `rNFT`

_Source: [`packages/metadata/src/rNFT/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/rNFT/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"rNFT"` | yes |  |
| `name` | string | yes |  |
| `description` | string | yes |  |
| `image` | string | no |  |
| `externalUrl` | string | yes |  |
| `licenseUrl` | string | yes |  |
| `condition` | string | no |  |
| `animationUrl` | string | no |  |
| `attributes` | object[] — see [attributes\[\]](#attributes-item) | no |  |

### `attributes[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `traitType` | string | yes |  |
| `value` | string | yes |  |
| `displayType` | string | no |  |

## `SELLER`

_Source: [`packages/metadata/src/seller/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/seller/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"SELLER"` | yes |  |
| `name` | string | no |  |
| `description` | string | no |  |
| `legalTradingName` | string | no |  |
| `kind` | string | yes |  |
| `website` | string | no |  |
| `images` | object[] — see [images\[\]](#images-item) | no |  |
| `contactLinks` | object[] — see [contactLinks\[\]](#contactlinks-item) | no |  |
| `contactPreference` | string | yes |  |
| `socialLinks` | object[] — see [socialLinks\[\]](#sociallinks-item) | no |  |
| `salesChannels` | object[] — see [salesChannels\[\]](#saleschannels-item) | no |  |

### `images[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | no |  |
| `type` | string | yes |  |
| `width` | number | no |  |
| `height` | number | no |  |
| `fit` | string | no |  |
| `position` | string | no |  |

### `contactLinks[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | yes |  |

### `socialLinks[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `tag` | string | yes |  |

### `salesChannels[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tag` | string | yes |  |
| `name` | string | no |  |
| `settingsUrl` | string | no |  |
| `settingsEditor` | string | no |  |
| `link` | string | no |  |
| `deployments` | object[] — see [salesChannels[].deployments\[\]](#saleschannels-item-deployments-item) | no |  |

### `salesChannels[].deployments[]`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object — see [salesChannels[].deployments[].product](#saleschannels-item-deployments-item-product) | no |  |
| `status` | string | no |  |
| `link` | string | no |  |
| `lastUpdated` | string | no |  |

### `salesChannels[].deployments[].product`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | no |  |
| `version` | number | no |  |

## `COLLECTION`

_Source: [`packages/metadata/src/collection/schema.json`](https://github.com/bosonprotocol/core-components/blob/main/packages/metadata/src/collection/schema.json)_

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaUrl` | string | yes |  |
| `type` | `"COLLECTION"` | yes |  |
| `name` | string | yes |  |
| `description` | string | no |  |
| `image` | string | no |  |
| `externalLink` | string | no |  |
| `external_link` | string | no |  |
| `collaborators` | string[] | no |  |


## Source

- Package: [`@bosonprotocol/metadata`](https://github.com/bosonprotocol/core-components/tree/main/packages/metadata)
- Schemas: [`packages/metadata/src/<domain>/schema.json`](https://github.com/bosonprotocol/core-components/tree/main/packages/metadata/src)

## Related

- [Concepts → The metadata pipeline](/concepts/metadata).
- [Troubleshooting → Metadata validation](/troubleshooting/metadata).

---

# Reference — React Kit

URL: https://www.bosonprotocol.io/docs/reference/react-kit

> Auto-generated stub. Components and hooks from @bosonprotocol/react-kit.

# React Kit

> :::info
> **Auto-generated stub** — regenerated from `@bosonprotocol/react-kit`.
> :::

:::warning
**Pre-release.** Hook and component surfaces are still settling. Pin exact versions.
:::

## Components

- `<BosonProvider configId="…">` — wraps your app and constructs the SDK.
- `<CommitButton offerId="…" />` — drop-in commit button.
- `<RedemptionFlow exchangeId="…" />` — buyer-side redemption flow.
- `<FinanceCard role="seller" accountId="…" />` — treasury management.

## Hooks

- `useCoreSdk()` — gets the configured SDK from context.
- `useOffers(filter)` — subgraph offers query, React Query-backed.
- `useExchanges(filter)` — same for exchanges.
- `useDisputes(filter)` — same for disputes.
- `useFunds(entityId)` — read available balances.
- `useCommit(offerId)` — encapsulates approve + commit.
- `useRedeem(exchangeId)` — encapsulates redeem.

## Source

- [`@bosonprotocol/react-kit`](https://github.com/bosonprotocol/core-components/tree/main/packages/react-kit)

---

# Reference — Subgraph queries

URL: https://www.bosonprotocol.io/docs/reference/subgraph

> Every GraphQL query and fragment shipped with @bosonprotocol/core-sdk, grouped by domain.

# Subgraph queries

:::info
**Generated from `core-components/packages/core-sdk/src/**/queries.graphql`. Edit the source GraphQL, not this page.**
:::

The Boson subgraph (one deployment per chain × env) indexes on-chain events into a GraphQL schema. The SDK and MCP both speak this schema; you can also query it directly with any GraphQL client.

For the endpoints, see [Networks → Subgraph endpoints](/networks/subgraph). For the eventing / indexing-lag model, see [Concepts → Eventing & indexing](/concepts/eventing).

## Health-check

```graphql
{
  _meta {
    block { number, hash }
    hasIndexingErrors
  }
}
```

Treat the subgraph as degraded if `_meta.block.number` falls more than ~20 blocks behind chain head, or if `hasIndexingErrors == true`.

## Per-domain catalogue

### `accounts`

_Source: [`accounts/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/accounts/queries.graphql)_

**Queries (9)**

| Name | Variables |
| --- | --- |
| `getAuthTokenIds` | `($tokenIdSkip: Int $tokenIdFirst: Int $authTokenType: Int)` |
| `getBuyerByIdQuery` | `($buyerId: ID! $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeExchanges: Boolean = false $includeFunds: Boolean = false $includeLogs: Boolean = false)` |
| `getBuyersQuery` | `($buyersSkip: Int $buyersFirst: Int $buyersOrderBy: Buyer_orderBy $buyersOrderDirection: OrderDirection $buyersFilter: Buyer_filter $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeExchanges: Boolean = false $includeOffers: Boolean = false $includeFunds: Boolean = false $includeLogs: Boolean = false)` |
| `getConditionalCommitAuthorizedEventLogsQuery` | `($conditionalCommitAuthorizedLogsSkip: Int $conditionalCommitAuthorizedLogsFirst: Int $conditionalCommitAuthorizedLogsOrderBy: ConditionalCommitAuthorizedEventLog_orderBy $conditionalCommitAuthorizedLogsOrderDirection: OrderDirection $conditionalCommitAuthorizedLogsFilter: ConditionalCommitAuthorizedEventLog_filter)` |
| `getDisputeResolverByIdQuery` | `($disputeResolverId: ID! $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeOffers: Boolean = false $includeLogs: Boolean = false)` |
| `getDisputeResolversQuery` | `($disputeResolversSkip: Int $disputeResolversFirst: Int $disputeResolversOrderBy: DisputeResolver_orderBy $disputeResolversOrderDirection: OrderDirection $disputeResolversFilter: DisputeResolver_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeOffers: Boolean = false $includeLogs: Boolean = false)` |
| `getOfferCollectionsQuery` | `($offerCollectionsSkip: Int $offerCollectionsFirst: Int $offerCollectionsOrderBy: OfferCollection_orderBy $offerCollectionsOrderDirection: OrderDirection $offerCollectionsFilter: OfferCollection_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $includeOffers: Boolean = false)` |
| `getSellerByIdQuery` | `($sellerId: ID! $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeExchanges: Boolean = false $includeOffers: Boolean = false $includeFunds: Boolean = false $includeLogs: Boolean = false)` |
| `getSellersQuery` | `($sellersSkip: Int $sellersFirst: Int $sellersOrderBy: Seller_orderBy $sellersOrderDirection: OrderDirection $sellersFilter: Seller_filter $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter $includeExchanges: Boolean = false $includeOffers: Boolean = false $includeFunds: Boolean = false $includeLogs: Boolean = false)` |

**Fragments (18):** `AuthTokenIdFields`, `BaseBuyerFields`, `BaseConditionalCommitAuthorizedEventLogsFields`, `BaseDisputeResolutionTermsEntityFields`, `BaseDisputeResolverFeeFields`, `BaseDisputeResolverFields`, `BaseOfferCollectionFields`, `BaseSellerFields`, `BuyerFields`, `DisputeResolverFields`, `OfferCollectionFields`, `PendingDisputeResolverFields`, `PendingSellerFields`, `SalesChannelFields`, `SellerContactLinkFields`, `SellerFields`, `SellerMetadataMediaFields`, `SellerSocialLinkFields`

### `disputes`

_Source: [`disputes/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/disputes/queries.graphql)_

**Queries (2)**

| Name | Variables |
| --- | --- |
| `getDisputeByIdQuery` | `($disputeId: ID! $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $includeOffers: Boolean = false)` |
| `getDisputesQuery` | `($disputesSkip: Int $disputesFirst: Int $disputesOrderBy: Dispute_orderBy $disputesOrderDirection: OrderDirection $disputesFilter: Dispute_filter)` |

**Fragments (2):** `BaseDisputeFields`, `DisputeFields`

### `erc20`

_Source: [`erc20/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/erc20/queries.graphql)_

**Queries (2)**

| Name | Variables |
| --- | --- |
| `getExchangeTokenByIdQuery` | `($exchangeTokenId: ID! $exchangeTokensSkip: Int $exchangeTokensFirst: Int $exchangeTokensOrderBy: ExchangeToken_orderBy $exchangeTokensOrderDirection: OrderDirection $exchangeTokensFilter: ExchangeToken_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $includeOffers: Boolean = false $includeFunds: Boolean = false)` |
| `getExchangeTokensQuery` | `($exchangeTokensSkip: Int $exchangeTokensFirst: Int $exchangeTokensOrderBy: ExchangeToken_orderBy $exchangeTokensOrderDirection: OrderDirection $exchangeTokensFilter: ExchangeToken_filter $offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $includeOffers: Boolean = false $fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter $includeFunds: Boolean = false)` |

**Fragments (2):** `BaseExchangeTokenFields`, `ExchangeTokenFields`

### `event-logs`

_Source: [`event-logs/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/event-logs/queries.graphql)_

**Queries (1)**

| Name | Variables |
| --- | --- |
| `getEventLogsQuery` | `($logsSkip: Int $logsFirst: Int $logsOrderBy: EventLog_orderBy $logsOrderDirection: OrderDirection $logsFilter: EventLog_filter)` |

**Fragments (1):** `BaseEventLogFields`

### `exchanges`

_Source: [`exchanges/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/exchanges/queries.graphql)_

**Queries (3)**

| Name | Variables |
| --- | --- |
| `getExchangeByIdQuery` | `($exchangeId: ID!)` |
| `getExchangesQuery` | `($exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter)` |
| `getNonListedOfferVoidedQuery` | `($nonListedOfferVoidedsSkip: Int $nonListedOfferVoidedsFirst: Int $nonListedOfferVoidedsOrderBy: NonListedOfferVoided_orderBy $nonListedOfferVoidedsOrderDirection: OrderDirection $nonListedOfferVoidedsFilter: NonListedOfferVoided_filter)` |

**Fragments (3):** `BaseExchangeFields`, `ExchangeFields`, `NonListedOfferVoidedFields`

### `funds`

_Source: [`funds/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/funds/queries.graphql)_

**Queries (2)**

| Name | Variables |
| --- | --- |
| `getFunds` | `($fundsSkip: Int $fundsFirst: Int $fundsOrderBy: FundsEntity_orderBy $fundsOrderDirection: OrderDirection $fundsFilter: FundsEntity_filter)` |
| `getFundsById` | `($fundsId: ID!)` |

**Fragments (2):** `BaseFundsEntityFields`, `FundsEntityFields`

### `groups`

_Source: [`groups/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/groups/queries.graphql)_

_No queries._

**Fragments (1):** `BaseConditionFields`

### `metadata`

_Source: [`metadata/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/metadata/queries.graphql)_

**Queries (11)**

| Name | Variables |
| --- | --- |
| `getAllProductsWithNotVoidedVariantsQuery` | `($productsSkip: Int $productsFirst: Int $productsOrderBy: ProductV1Product_orderBy $productsOrderDirection: OrderDirection $productsFilter: ProductV1Product_filter)` |
| `getBaseMetadataEntitiesQuery` | `($metadataSkip: Int $metadataFirst: Int $metadataOrderBy: BaseMetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: BaseMetadataEntity_filter)` |
| `getBaseMetadataEntityByIdQuery` | `($metadataId: ID! $metadataSkip: Int $metadataFirst: Int $metadataOrderBy: BaseMetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: BaseMetadataEntity_filter)` |
| `getBundleMetadataEntitiesQuery` | `($metadataSkip: Int $metadataFirst: Int $metadataOrderBy: BundleMetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: BundleMetadataEntity_filter)` |
| `getBundleMetadataEntityByIdQuery` | `($metadataId: ID! $metadataSkip: Int $metadataFirst: Int $metadataOrderBy: BundleMetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: BundleMetadataEntity_filter)` |
| `getProductV1BrandsQuery` | `($brandsSkip: Int $brandsFirst: Int $brandsOrderBy: ProductV1Brand_orderBy $brandsOrderDirection: OrderDirection $brandsFilter: ProductV1Brand_filter)` |
| `getProductV1CategoriesQuery` | `($categoriesSkip: Int $categoriesFirst: Int $categoriesOrderBy: ProductV1Category_orderBy $categoriesOrderDirection: OrderDirection $categoriesFilter: ProductV1Category_filter)` |
| `getProductV1MetadataEntitiesQuery` | `($metadataSkip: Int $metadataFirst: Int $metadataOrderBy: ProductV1MetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: ProductV1MetadataEntity_filter)` |
| `getProductV1MetadataEntityByIdQuery` | `($metadataId: ID! $metadataSkip: Int $metadataFirst: Int $metadataOrderBy: ProductV1MetadataEntity_orderBy $metadataOrderDirection: OrderDirection $metadataFilter: ProductV1MetadataEntity_filter)` |
| `getProductV1ProductsQuery` | `($productsSkip: Int $productsFirst: Int $productsOrderBy: ProductV1Product_orderBy $productsOrderDirection: OrderDirection $productsFilter: ProductV1Product_filter)` |
| `getProductV1ProductsWithVariantsQuery` | `($productsSkip: Int $productsFirst: Int $productsOrderBy: ProductV1Product_orderBy $productsOrderDirection: OrderDirection $productsFilter: ProductV1Product_filter)` |

**Fragments (23):** `BaseAnimationMetadataFields`, `BaseBaseMetadataEntityFields`, `BaseBundleMetadataEntityFields`, `BaseMetadataEntityFields`, `BaseProductV1BrandFields`, `BaseProductV1CategoryFields`, `BaseProductV1ExchangePolicyFields`, `BaseProductV1MediaFields`, `BaseProductV1MetadataEntityFields`, `BaseProductV1PersonalisationFields`, `BaseProductV1ProductFields`, `BaseProductV1ProductOverridesFields`, `BaseProductV1ProductWithNotVoidedVariantsFields`, `BaseProductV1ProductWithVariantsFields`, `BaseProductV1SectionFields`, `BaseProductV1SellerContactLinkFields`, `BaseProductV1SellerFields`, `BaseProductV1ShippingJurisdictionFields`, `BaseProductV1ShippingOptionFields`, `BaseProductV1TagFields`, `BaseProductV1VariationFields`, `BundleMetadataEntityFields`, `ProductV1MetadataEntityFields`

### `offers`

_Source: [`offers/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/offers/queries.graphql)_

**Queries (3)**

| Name | Variables |
| --- | --- |
| `getOfferByIdQuery` | `($offerId: ID! $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $includeExchanges: Boolean = false)` |
| `getOffersMediaQuery` | `($offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $includeExchanges: Boolean = false)` |
| `getOffersQuery` | `($offersSkip: Int $offersFirst: Int $offersOrderBy: Offer_orderBy $offersOrderDirection: OrderDirection $offersFilter: Offer_filter $exchangesSkip: Int $exchangesFirst: Int $exchangesOrderBy: Exchange_orderBy $exchangesOrderDirection: OrderDirection $exchangesFilter: Exchange_filter $includeExchanges: Boolean = false)` |

**Fragments (3):** `BaseOfferFields`, `BaseRangeFields`, `OfferFields`

### `search`

_Source: [`search/queries.graphql`](https://github.com/bosonprotocol/core-components/blob/main/packages/core-sdk/src/search/queries.graphql)_

**Queries (1)**

| Name | Variables |
| --- | --- |
| `searchProductsQuery` | `($productsSkip: Int $productsFirst: Int $productsOrderBy: ProductV1Product_orderBy $productsOrderDirection: OrderDirection $productsFilter: ProductV1Product_filter)` |

**Fragments (1):** `ProductSearchResultFields`

## Source

- SDK queries: [`packages/core-sdk/src/**/queries.graphql`](https://github.com/bosonprotocol/core-components/tree/main/packages/core-sdk/src)
- Subgraph mappings & schema: [`@bosonprotocol/subgraph`](https://github.com/bosonprotocol/core-components/tree/main/packages/subgraph)

## Related

- [Concepts → Eventing & indexing](/concepts/eventing)
- [Networks → Subgraph endpoints](/networks/subgraph)

---

# Reference — Widget URL params

URL: https://www.bosonprotocol.io/docs/reference/widget-params

> Every parameter accepted by hosted widgets.

# Widget URL params

> :::info
> Hand-maintained today; will be auto-generated from `widgets/` repo prop types in a future pass.
> :::

Every hosted widget reads the same parameters from either `data-*` attributes (script + button), URL query string (iframe), or Zoid props.

## Universal

| Param | Required? | Notes |
| --- | --- | --- |
| `configId` | Yes | See [Networks → ConfigIds matrix](/networks/configids) |
| `account` | No | Restrict to a single wallet |
| `lookAndFeel` | No | `"modal"` (default) or `"regular"` |
| `themeOverrides` | No | JSON string of CSS variable overrides |
| `postbackUrl` | No | Server URL for HMAC-signed lifecycle posts |
| `postbackSecret` | No | HMAC secret (omit for unsigned posts) |

## Commit Widget

| Param | Notes |
| --- | --- |
| `sellerId` | Show offers from one seller |
| `productUuid` | Targets a product (incl. variants) |
| `bundleUuid` | Targets a bundle |
| `offerId` | Targets a single offer |
| `redirectUrl` | Where to redirect after commit |

## Redemption Widget

| Param | Notes |
| --- | --- |
| `sellerId` | Filter to one seller |
| `exchangeId` | Open directly to one exchange |
| `deliveryInfoUrl` | Endpoint to POST collected delivery info |

## Finance Widget

| Param | Notes |
| --- | --- |
| `role` | `"seller"`, `"buyer"`, `"disputeResolver"`, `"agent"` |
| `accountId` | The on-chain ID for that entity |

## Source

- Widgets: [`bosonprotocol/widgets`](https://github.com/bosonprotocol/widgets)

---

# Reference — x402-actions

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-actions

> State machine and nextActions envelope builder.

# `@bosonprotocol/x402-actions`

> :::info
> **Auto-generated stub.**
> :::

## Exports

- `Channel` — `"onchain" | "facilitator" | "server" | "mcp"`.
- `ChannelAdapter` — interface; one adapter per channel.
- `FacilitatorChannelAdapter`, `OnchainChannelAdapter`, etc.
- `computeNextActions({ state, role })` — return legal transitions.
- `buildNextActionsEnvelope({ state, channels, endpoints })`.

## Source

- [`x402-actions`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-actions/src)

## Related

- [Build with x402 → State-machine integration](/x402/state-machine)

---

# Reference — x402-client

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-client

> Framework-agnostic buyer-side SDK for x402b.

# `@bosonprotocol/x402-client` (+ `-fetch`)

> :::info
> **Auto-generated stub.**
> :::

## Exports (x402-client)

- `createX402bClient({ signer, preferences })`.
- `buildPayment(challenge)` — produce the `X-PAYMENT` header value.
- `parseChallenge(rawResponse)` — decode a 402 response.

## Exports (x402-client-fetch)

- `createX402bClientFetch({ signer, preferences })` — drop-in replacement for `fetch` that handles 402s transparently.

## Source

- [`x402-client`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-client/src)
- [`x402-client-fetch`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-client-fetch/src)

---

# Reference — x402-core

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-core

> Schemas, zod validators, EIP-712 builders, and the state machine for x402b.

# `@bosonprotocol/x402-core`

> :::info
> **Auto-generated stub** — regenerated from `x402b/typescript/packages/x402-core`.
> :::

The primitive layer of the x402b stack. Other packages depend on this.

## Exports

- **Schemas**: zod validators for the `escrow` scheme wire format (402 response shape, X-PAYMENT header shape).
- **EIP-712 builders**: typed-data domain + types for `FullOffer`, the meta-tx envelope, and four token-auth strategies.
- **State machine**: states (`awaiting_redemption`, `awaiting_fulfillment`, `delivered`, `completed`, `disputed`, `accepted`, `shipped`, `finalized`), legal transitions, and `boson-*` action IDs.
- **Errors**: tagged `EscrowError` types with codes.

## Source

- [`x402b/typescript/packages/x402-core/src`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-core/src)

---

# Reference — x402-evm

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-evm

> EVM calldata builders for the deferred and atomic x402b flows.

# `@bosonprotocol/x402-evm`

> :::info
> **Auto-generated stub.**
> :::

EVM-specific calldata for the two x402b flows.

## Exports

- `buildCreateOfferAndCommitCalldata(...)` — deferred flow: commit now, redeem later.
- `buildCreateOfferCommitAndRedeemCalldata(...)` — atomic flow.
- `walletClientToWeb3LibAdapter(viemClient)` — viem → SDK adapter bridge.
- `RelayerSubmitError` — tagged error for facilitator failures.

## Source

- [`x402b/typescript/packages/x402-evm/src`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-evm/src)

---

# Reference — x402-facilitator

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-facilitator

> Reference relayer for x402b.

# `@bosonprotocol/x402-facilitator` (+ `-express`)

> :::info
> **Auto-generated stub.**
> :::

## Exports (x402-facilitator)

- `verify(paymentPayload, config)`.
- `settle(paymentPayload, config)` → `{ ok, exchangeId, txHash } | { ok: false, code, reason }`.
- `performAction(payload, config)` — settle and advance the exchange.
- `FacilitatorChannelAdapter` — for `nextActions[]` envelope integration.

## Exports (x402-facilitator-express)

- `createX402bFacilitatorExpress(opts)` — express handler.

## Source

- [`x402-facilitator`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-facilitator/src)
- [`x402-facilitator-express`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-facilitator-express/src)

---

# Reference — x402-fulfillment

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-fulfillment

> Pluggable fulfillment channels.

# `@bosonprotocol/x402-fulfillment`

> :::info
> **Auto-generated stub.**
> :::

## Exports

- `FulfillmentChannel` — interface (`id`, `fulfill(ctx)`).
- `ChannelRegistry` — registers channels by id, picks one based on advertised options.
- Built-in channels: `inline`, `email`, `xmtp`, `webhook`, `ipfsPointer` (when shipped).

## Source

- [`x402-fulfillment`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-fulfillment/src)

## Related

- [Concepts → Fulfillment channels](/concepts/fulfillment)
- [Build with x402 → Fulfillment channels](/x402/fulfillment)

---

# Reference — x402-server

URL: https://www.bosonprotocol.io/docs/reference/x402/x402-server

> Framework-agnostic resource-server SDK for x402b.

# `@bosonprotocol/x402-server` (+ `-express`)

> :::info
> **Auto-generated stub.**
> :::

## Exports (x402-server)

- `createX402bServer({ network, chainId, escrow, signer, facilitator, channelRegistry })`.
- `buildPaymentRequirements({ offer, asset, amount, tokenAuthStrategies, channelRegistry })`.
- `verifyPaymentHeader(headerValue)`.

## Exports (x402-server-express)

- `createX402bServerExpress(opts)` — express middleware.

## Source

- [`x402-server`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-server/src)
- [`x402-server-express`](https://github.com/bosonprotocol/x402b/tree/main/typescript/packages/x402-server-express/src)

---

# Networks & addresses

URL: https://www.bosonprotocol.io/docs/networks

> Every deployment, contract address, subgraph endpoint, MCP server URL, and supported token, in one place.

# Networks & addresses

This section is a set of **everything-as-a-table** pages auto-generated from the canonical sources:

- ConfigIds — from `getConfigFromConfigId()` / `getEnvConfigs()` in `@bosonprotocol/common`.
- Contract addresses — from `boson-protocol-contracts/addresses/*.json`.
- Subgraph endpoints — from per-config metadata in `@bosonprotocol/common`.
- MCP server URLs — from the `agentic-commerce` deployment config.
- Supported tokens — from `get_supported_tokens` (MCP) and config metadata.

## Pages

- [ConfigIds matrix](./networks/configids) — env × chain × index → string.
- [Contract addresses](./networks/addresses) — Diamond, voucher, forwarder, Permit2, etc.
- [Subgraph endpoints](./networks/subgraph) — GraphQL URLs per chain × env.
- [MCP server URLs](./networks/mcp-urls) — staging vs production.
- [Supported tokens](./networks/tokens) — accepted ERC-20s per chain.

## Why a separate section

These tables are queried constantly during integration ("what's the Diamond on Base?", "where do I point the subgraph?"). Keeping them in one place — and machine-readable — lets:

- Build pages and recipes link to a single canonical row.
- LLM clients fetch the JSON-rendered version via the auto-generated machine surface.
- Reference pages stay short.

---

# Networks — Contract addresses

URL: https://www.bosonprotocol.io/docs/networks/addresses

> Diamond, voucher, forwarder, Permit2, and helper contract addresses per chain × env.

# Contract addresses

:::info
**Generated from `boson-protocol-contracts`/addresses. Edit the source JSON, not this page.**
:::

Each chain × env has its own deployment. The `ProtocolDiamond` is the main entry point; cast it to any facet interface.

For the canonical JSON, browse [`boson-protocol-contracts/addresses`](https://github.com/bosonprotocol/boson-protocol-contracts/tree/main/addresses).

## Read at runtime

```ts twoslash
// @noErrors
import { getConfigFromConfigId } from "@bosonprotocol/common"
const config = getConfigFromConfigId("production-137-0")
console.log(config.contracts.protocolDiamond)
```

## Verifying

Before integrating, verify the address you got against the table below. The Diamond is the same address per chain × env × index for the lifetime of that deployment.

## Deployments

### Ethereum mainnet — production  
_ConfigId: `production-1-0` · chainId: `1` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x59A4C19b55193D5a2EAD0065c54af4d516E18Cb5` |

### Optimism — production  
_ConfigId: `production-10-0` · chainId: `10` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x59A4C19b55193D5a2EAD0065c54af4d516E18Cb5` |

### Polygon — production  
_ConfigId: `production-137-0` · chainId: `137` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x59A4C19b55193D5a2EAD0065c54af4d516E18Cb5` |

### Base — production  
_ConfigId: `production-8453-0` · chainId: `8453` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x59A4C19b55193D5a2EAD0065c54af4d516E18Cb5` |

### Arbitrum One — production  
_ConfigId: `production-42161-0` · chainId: `42161` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x59A4C19b55193D5a2EAD0065c54af4d516E18Cb5` |

### Polygon Amoy — staging  
_ConfigId: `staging-80002-0` · chainId: `80002` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x26f643746cbc918b46c2d47edca68c4a6c98ebe6` |

### Base Sepolia — staging  
_ConfigId: `staging-84532-0` · chainId: `84532` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x26f643746cbc918b46c2d47edca68c4a6c98ebe6` |

### Arbitrum Sepolia — staging  
_ConfigId: `staging-421614-0` · chainId: `421614` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x26f643746cbc918b46c2d47edca68c4a6c98ebe6` |

### Sepolia (Ethereum testnet) — staging  
_ConfigId: `staging-11155111-0` · chainId: `11155111` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x26f643746cbc918b46c2d47edca68c4a6c98ebe6` |

### Optimism Sepolia — staging  
_ConfigId: `staging-11155420-0` · chainId: `11155420` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x26f643746cbc918b46c2d47edca68c4a6c98ebe6` |

### Custom test — testing  
_ConfigId: `testing-1234-0` · chainId: `1234` · protocol `2.0.0-rc.1`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x1F14e71c47ED9496D8383F8FcD18D0F488915746` |

### Polygon Amoy — testing  
_ConfigId: `testing-80002-0` · chainId: `80002` · protocol `2.5.0-rc.2`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x7de418a7ce94debd057c34ebac232e7027634ade` |

### Base Sepolia — testing  
_ConfigId: `testing-84532-0` · chainId: `84532` · protocol `2.5.0`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x7de418a7ce94debd057c34ebac232e7027634ade` |

### Arbitrum Sepolia — testing  
_ConfigId: `testing-421614-0` · chainId: `421614` · protocol `2.5.0-rc.2`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x7de418a7ce94debd057c34ebac232e7027634ade` |

### Sepolia (Ethereum testnet) — testing  
_ConfigId: `testing-11155111-0` · chainId: `11155111` · protocol `2.5.0-rc.2`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x7de418a7ce94debd057c34ebac232e7027634ade` |

### Optimism Sepolia — testing  
_ConfigId: `testing-11155420-0` · chainId: `11155420` · protocol `2.5.0-rc.2`_

| Contract | Address |
| --- | --- |
| `ProtocolDiamond` | `0x7de418a7ce94debd057c34ebac232e7027634ade` |

## Related

- [Quickstart → Call Boson from Solidity](/quickstart/solidity)
- [Concepts → Architecture](/concepts/architecture)

---

# Networks — ConfigIds matrix

URL: https://www.bosonprotocol.io/docs/networks/configids

> Every known ConfigId, the chain it points to, and the protocol version deployed.

# ConfigIds matrix

:::info
**Generated from `boson-protocol-contracts`/addresses. Edit the source JSON, not this page.**
:::

ConfigId format: `${envName}-${chainId}-${index}`. See [Concepts → Networks & ConfigIds](/concepts/networks-and-configids) for the model.

## Production

| ConfigId | Chain | Chain ID | Protocol version |
| --- | --- | --- | --- |
| `production-1-0` | Ethereum mainnet | 1 | 2.5.0 |
| `production-10-0` | Optimism | 10 | 2.5.0 |
| `production-137-0` | Polygon | 137 | 2.5.0 |
| `production-8453-0` | Base | 8453 | 2.5.0 |
| `production-42161-0` | Arbitrum One | 42161 | 2.5.0 |

## Staging (testnets)

| ConfigId | Chain | Chain ID | Protocol version |
| --- | --- | --- | --- |
| `staging-80002-0` | Polygon Amoy | 80002 | 2.5.0 |
| `staging-84532-0` | Base Sepolia | 84532 | 2.5.0 |
| `staging-421614-0` | Arbitrum Sepolia | 421614 | 2.5.0 |
| `staging-11155111-0` | Sepolia (Ethereum testnet) | 11155111 | 2.5.0 |
| `staging-11155420-0` | Optimism Sepolia | 11155420 | 2.5.0 |

## Test

| ConfigId | Chain | Chain ID | Protocol version |
| --- | --- | --- | --- |
| `testing-1234-0` | Custom test | 1234 | 2.0.0-rc.1 |
| `testing-80002-0` | Polygon Amoy | 80002 | 2.5.0-rc.2 |
| `testing-84532-0` | Base Sepolia | 84532 | 2.5.0 |
| `testing-421614-0` | Arbitrum Sepolia | 421614 | 2.5.0-rc.2 |
| `testing-11155111-0` | Sepolia (Ethereum testnet) | 11155111 | 2.5.0-rc.2 |
| `testing-11155420-0` | Optimism Sepolia | 11155420 | 2.5.0-rc.2 |

## Discover at runtime

```ts twoslash
// @noErrors
import { getEnvConfigs } from "@bosonprotocol/common"
const ids = (["local", "testing", "staging", "production"] as const)
  .flatMap((env) => getEnvConfigs(env).map((c) => c.configId))
```

Or via MCP: `get_config_ids`.

## Related

- [Networks → Contract addresses](./addresses)
- [Networks → Subgraph endpoints](./subgraph)
- [Concepts → Networks & ConfigIds](/concepts/networks-and-configids)

---

# Networks — MCP server URLs

URL: https://www.bosonprotocol.io/docs/networks/mcp-urls

> The hosted Boson MCP endpoints.

# MCP server URLs

| Env | URL |
| --- | --- |
| Staging | `https://mcp-staging.bosonprotocol.io/mcp` |
| Production | `https://mcp.bosonprotocol.io/mcp` |

## Self-hosting

```bash
npx @bosonprotocol/agentic-commerce boson-mcp-server --mode http --port 8080
```

See [Build for AI agents → Hosted vs self-hosted MCP](/agents/mcp-deployment).

## Fermion (high-value asset module) MCP

> Separate hosted server with verifier / custodian tools. URL TBD; see [Build for AI agents → High-value asset module](/agents/fermion).

## Related

- [Tooling → MCP / agent stack](/tooling/mcp)
- [Quickstart → Buy with an AI agent](/quickstart/ai-agent-buyer)

---

# Networks — Subgraph endpoints

URL: https://www.bosonprotocol.io/docs/networks/subgraph

> GraphQL endpoint URLs per chain × env.

# Subgraph endpoints

> :::info
> **Auto-generated** — list pulled from `@bosonprotocol/common` config at build time.
> :::

Each chain × env has its own subgraph hosted on The Graph (or a self-hosted equivalent). The SDK and MCP both read from these.

## At runtime

```ts twoslash
// @noErrors
import { getConfigFromConfigId } from "@bosonprotocol/common"
const config = getConfigFromConfigId("production-137-0")
console.log(config.subgraphUrl)
```

## Direct GraphQL access

You can query the subgraph directly with any GraphQL client:

```ts twoslash
// @noErrors
import { request, gql } from "graphql-request"

const data = await request(
  config.subgraphUrl,
  gql`{ offers(first: 10, where: { voided: false }) { id, price, exchangeToken } }`,
)
```

## Health-check

```graphql
{
  _meta {
    block { number }
    hasIndexingErrors
  }
}
```

Treat the subgraph as degraded if `_meta.block.number` is more than ~20 behind chain head, or if `hasIndexingErrors == true`.

## Related

- [Concepts → Eventing & indexing](/concepts/eventing)
- [Reference → Subgraph queries](/reference/subgraph)

---

# Networks — Supported tokens

URL: https://www.bosonprotocol.io/docs/networks/tokens

> Which ERC-20 tokens are accepted as offer exchangeToken on which chain.

# Supported tokens

> :::info
> **Auto-generated** — pulled from `get_supported_tokens` (MCP) and `@bosonprotocol/common` configs.
> :::

Each chain has a set of tokens accepted as `exchangeToken` on offers. Native gas tokens (ETH, MATIC) are always supported and represented as `0x0000…0000`.

## Reading at runtime

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
const sdk = CoreSDK.fromDefaultConfig({ web3Lib, configId: "production-137-0" })
const tokens = await sdk.getSupportedTokens()
// → [{ address, name, symbol, decimals }, …]
```

Or via MCP: `get_supported_tokens`.

## Typical lineup

| Chain | Native | USDC | USDT | DAI | EURC | Other |
| --- | --- | --- | --- | --- | --- | --- |
| Polygon (137) | MATIC | ✅ | ✅ | ✅ | ✅ | (subject to update) |
| Ethereum (1) | ETH | ✅ | ✅ | ✅ | ✅ | |
| Base (8453) | ETH | ✅ | — | — | ✅ | |
| Optimism (10) | ETH | ✅ | ✅ | ✅ | — | |
| Arbitrum (42161) | ETH | ✅ | ✅ | ✅ | — | |

_The actual list is config-driven and may differ; always check at runtime._

## Common gotchas

- **Token addresses are chain-specific.** USDC on Polygon ≠ USDC on Base. Don't reuse addresses across chains.
- **Decimals vary.** USDC is 6 decimals; DAI is 18. Don't hard-code.
- **Adding a token is a config change.** If a token you want isn't listed, open an issue or PR against the config.

## Related

- [Concepts → Funds, escrow & payouts](/concepts/funds)
- [Troubleshooting → Approve · Permit · Permit2](/troubleshooting/approvals)

---

# Recipes

URL: https://www.bosonprotocol.io/docs/recipes

> Copy-paste end-to-end flows — each page is a single context window for an LLM.

# Recipes

Each recipe is a **single MDX page** with a complete copy-paste flow. You can lift the whole page into an LLM's context, point it at your stack, and get a working integration.

Recipes pull from `agentic-commerce/e2e/boson/tests/complete-marketplace-journeys.test.ts` — the canonical end-to-end reference.

## Full flows

- [E2E seller flow](./recipes/e2e-seller) — register → list → fulfill → withdraw.
- [E2E buyer flow](./recipes/e2e-buyer) — browse → commit → redeem.
- [Mutual dispute resolution](./recipes/mutual-dispute) — both sides sign, one submits.

## Common patterns

- [Token-gated launch](./recipes/token-gated) — restrict offers to NFT holders.
- [Digital + physical bundle](./recipes/bundle) — one offer, two items.
- [ERC-20 approve + commit](./recipes/erc20-commit) — the two-step path.
- [Gas-less commit (Biconomy)](./recipes/gasless-commit) — meta-tx via relayer.
- [Threshold-buy agent](./recipes/threshold-buy-agent) — autonomous buyer that watches and pulls the trigger.
- [Webhook server for state changes](./recipes/webhook-server) — production-grade event listener.

## x402 recipes

- [x402 buyer paying for a digital asset](./recipes/x402-buyer).
- [x402 server email-fulfillment](./recipes/x402-email).

## Non-code

- [Sell via WooCommerce](./recipes/woocommerce) — plugin install and configuration.

## Migration

- [Migrate from legacy v2](./recipes/migrate-v2) — for teams coming from the older Boson stack.

## Why recipes are separate from Build

**Build** pages explain a single task ("publish an offer") with stack-tabbed snippets. **Recipes** combine multiple tasks into a working program. The same content might appear in both, but Build is task-focused didactics and Recipes is copy-paste integration. Pick whichever matches what you're trying to do.

---

# Recipe — Digital + physical bundle

URL: https://www.bosonprotocol.io/docs/recipes/bundle

> One offer that ships a physical good and a digital access pass together.

# Recipe: Digital + physical bundle

A bundle is a single offer that represents multiple items. The buyer commits once; redemption delivers all items.

```ts twoslash
// @noErrors
// Build BUNDLE metadata directly per the schema — there's no
// bundleMetadataFactory export. See Reference → Metadata schemas for the
// full shape (required top-level fields: schemaUrl, type, uuid, name,
// description, externalUrl, licenseUrl, image, attributes, items, seller).
const uuid = crypto.randomUUID()
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "BUNDLE" as const,
  uuid,
  name: "Hoodie + Discord access",
  description: "A limited hoodie and one year of Discord access.",
  externalUrl: `https://example.com/${uuid}`,
  licenseUrl: `https://example.com/${uuid}/license`,
  image: "https://cdn.example.com/bundle.jpg",
  attributes: [
    { traitType: "Type", value: "Bundle" },
    { traitType: "Items", value: "2" },
  ],
  items: [
    { type: "ITEM_PRODUCT_V1", productV1: { /* full PRODUCT_V1 item — see Reference → Metadata schemas */ } },
    { type: "ITEM_NFT", nft: { name: "Discord access pass", description: "1 year of access to our Discord.", image: "https://cdn.example.com/pass.png" } },
  ],
  seller: { defaultVersion: 1, name: "Your brand", contactLinks: [{ tag: "email", url: "mailto:hi@example.com" }] },
}

const metadataUri = await sdk.storeMetadata(metadata)
await sdk.createOffer({ /* … */, metadataUri, metadataHash: metadataUri.replace(/^ipfs:\/\//, "") })
```

## At redemption

When the buyer redeems, your fulfillment system delivers both items:
- Physical: ship the hoodie via your normal logistics.
- Digital: send the Discord invite via email / XMTP / postback.

Boson doesn't separate the two — they're a single exchange with a single redemption. If something goes wrong with one item, the dispute is over the whole bundle.

## Related

- [Reference → Metadata schemas → BUNDLE](/reference/metadata)
- [Build → Sellers → Bundles & variants](/build/sellers/bundles-variants)

---

# Recipe — E2E buyer flow

URL: https://www.bosonprotocol.io/docs/recipes/e2e-buyer

> Browse → commit → redeem. Including ERC-20 approval and indexing-lag handling.

# Recipe: End-to-end buyer flow

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { ethers } from "ethers"

const CONFIG_ID = "staging-84532-0" as const
const ENV_NAME = "staging" as const

async function main() {
  const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL)
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)
  const sdk = CoreSDK.fromDefaultConfig({
    web3Lib: new EthersAdapter(provider, wallet),
    envName: ENV_NAME,
    configId: CONFIG_ID,
  })

  // 1. Find an offer
  const offers = await sdk.getOffers({
    where: { voided: false, exchangeToken: USDC_ADDRESS },
    orderBy: "price",
    orderDirection: "asc",
    first: 10,
  })
  const pick = offers[0]
  const tokenAddr = pick.exchangeToken.address ?? pick.exchangeToken
  console.log("buying offer", pick.id, "for", pick.price, tokenAddr)

  // 2. Approve the ERC-20 (first arg is the TOKEN address, not the offer id)
  await (await sdk.approveExchangeToken(tokenAddr, pick.price)).wait()

  // 3. Commit — commitToOffer(offerId, overrides?); buyer is the signer.
  const commitTx = await sdk.commitToOffer(pick.id)
  const receipt = await commitTx.wait()
  await sdk.waitForGraphNodeIndexing(receipt.blockNumber)
  const exchangeId = sdk.getCommittedExchangeIdFromLogs(receipt.logs)
  console.log("committed. exchangeId =", exchangeId)

  // 4. Wait for delivery (off-chain, your system)
  await waitForDelivery(exchangeId)

  // 5. Redeem
  await (await sdk.redeemVoucher(exchangeId)).wait()
  console.log("redeemed.")
}
```

## Common variations

- **Native-token offers** — skip step 2; pass `{ value: pick.price }` on step 3.
- **Atomic commit-and-redeem** — see [Buyers → Atomic commit-and-redeem](/build/buyers/atomic-commit-redeem); the SDK currently exposes two-step commit+redeem, with a single-tx variant available via the Diamond's `OrchestrationHandlerFacet`.
- **Gas-less commit** — see [Recipe → Gas-less commit](./gasless-commit).
- **Token-gated** — same flow; the commit reverts if you don't hold the gating token.

## Related

- [Build → Buyers](/build/buyers)
- [Quickstart → Build a marketplace](/quickstart/marketplace)

---

# Recipe — E2E seller flow

URL: https://www.bosonprotocol.io/docs/recipes/e2e-seller

> Register → list → handle redemption → withdraw. A working script you can adapt.

# Recipe: End-to-end seller flow

A complete seller lifecycle in one script. Adapted from [`agentic-commerce/e2e/boson/tests/complete-marketplace-journeys.test.ts`](https://github.com/bosonprotocol/agentic-commerce/blob/main/e2e/boson/tests/complete-marketplace-journeys.test.ts).

**Stack**: TypeScript, ethers v5, `@bosonprotocol/core-sdk`. **Network**: Base Sepolia.

## Setup

```bash
pnpm add @bosonprotocol/core-sdk @bosonprotocol/ethers-sdk @bosonprotocol/metadata @bosonprotocol/ipfs-storage ethers@^5
export PRIVATE_KEY=0x...
export RPC_URL=https://sepolia.base.org
# IPFS — use an authenticated pinning endpoint. The protocol default points at
# Infura, which now requires a project id. Pinata, web3.storage, or your own
# Kubo node all work; pass an authenticated URL via process.env.IPFS_URL.
export IPFS_URL=https://your-pinning-endpoint
```

## The script

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"
import { EthersAdapter } from "@bosonprotocol/ethers-sdk"
import { IpfsMetadataStorage } from "@bosonprotocol/ipfs-storage"
import { validateMetadata } from "@bosonprotocol/metadata"
import { getConfigFromConfigId } from "@bosonprotocol/common"
import { ethers } from "ethers"
import fs from "node:fs"

const CONFIG_ID = "staging-84532-0" as const
const ENV_NAME = "staging" as const

async function main() {
  const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL)
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

  const sdk = CoreSDK.fromDefaultConfig({
    web3Lib: new EthersAdapter(provider, wallet),
    envName: ENV_NAME,
    configId: CONFIG_ID,
    metadataStorage: new IpfsMetadataStorage(validateMetadata, { url: process.env.IPFS_URL! }),
  })

  // 1. Create the seller (if not already created)
  let seller = (await sdk.getSellersByAddress(wallet.address))[0]
  if (!seller) {
    const tx = await sdk.createSeller({
      assistant: wallet.address,
      admin: wallet.address,
      treasury: wallet.address,
      contractUri: "ipfs://Qm…",
      royaltyPercentage: "0",
      authTokenId: "0",
      authTokenType: 0,
      metadataUri: "ipfs://Qm…",
    })
    const receipt = await tx.wait()
    await sdk.waitForGraphNodeIndexing(receipt.blockNumber)
    seller = (await sdk.getSellersByAddress(wallet.address))[0]
  }
  console.log("seller.id =", seller.id)

  // 2. Build & pin metadata. There's no productV1MetadataFactory — construct
  //    the PRODUCT_V1 object directly per the schema.
  const uuid = crypto.randomUUID()
  const metadata = {
    schemaUrl: "https://schema.org/Product",
    type: "PRODUCT_V1" as const,
    uuid,
    name: "Test mug",
    description: "Stoneware, 12 oz.",
    externalUrl: `https://example.com/${uuid}`,
    licenseUrl: `https://example.com/${uuid}/license`,
    image: "https://example.com/mug.jpg",
    attributes: [
      { traitType: "Material", value: "Stoneware" },
      { traitType: "Size", value: "12 oz" },
    ],
    product: {
      uuid, version: 1,
      title: "Test mug", description: "Stoneware, 12 oz.",
      productionInformation_brandName: "Your brand",
      details_offerCategory: "PHYSICAL",
      visuals_images: [{ url: "https://example.com/mug.jpg", tag: "product" }],
    },
    seller: { defaultVersion: 1, name: "Your brand", contactLinks: [{ tag: "email", url: "mailto:hi@example.com" }] },
    shipping: { returnPeriod: "14" },
    exchangePolicy: { uuid: crypto.randomUUID(), version: 1, label: "fairExchangePolicy", template: "ipfs://Qm-template", sellerContactMethod: "email", disputeResolverContactMethod: "email" },
  }
  const metadataUri = await sdk.storeMetadata(metadata)

  // 3. Create the offer
  const offerTx = await sdk.createOffer({
    price: "1000000",
    sellerDeposit: "0",
    buyerCancelPenalty: "0",
    quantityAvailable: "10",
    exchangeToken: USDC_ADDRESS,
    metadataUri,
    metadataHash: metadataUri.replace(/^ipfs:\/\//, ""),  // IPFS CID is the hash
    validFromDateInMS: Date.now(),
    validUntilDateInMS: Date.now() + 30 * 24 * 60 * 60 * 1000,
    voucherRedeemableFromDateInMS: Date.now(),
    voucherRedeemableUntilDateInMS: 0,
    voucherValidDurationInMS: 30 * 24 * 60 * 60 * 1000,
    disputePeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
    resolutionPeriodDurationInMS: 7 * 24 * 60 * 60 * 1000,
    collectionIndex: "0",
    disputeResolverId: "5",                                // your chain's DR; look up via sdk.getDisputeResolvers()
    agentId: "0",
    feeLimit: ethers.constants.MaxUint256.toString(),     // accept any fee
  })
  const offerReceipt = await offerTx.wait()
  await sdk.waitForGraphNodeIndexing(offerReceipt.blockNumber)
  console.log("offer published.")

  // 4. Listen for VoucherRedeemed and "deliver". No sdk.getDiamondContract() —
  //    build the contract yourself using the relevant facet ABI.
  const exchangeAbi = JSON.parse(fs.readFileSync(
    "node_modules/@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json", "utf8"
  ))
  const config = getConfigFromConfigId(CONFIG_ID)
  const diamond = new ethers.Contract(config.contracts.protocolDiamond, exchangeAbi, provider)
  diamond.on("VoucherRedeemed", async (offerId, exchangeId) => {
    console.log("redeemed:", exchangeId.toString())
    // (your delivery system here)
  })

  // 5. After the dispute window, complete & withdraw
  // (in production, schedule this as a periodic job)
  const redeemed = await sdk.getExchanges({
    where: { seller: seller.id, state: "REDEEMED" },
  })
  for (const ex of redeemed) {
    if (Date.now() > Number(ex.disputePeriodEnd) * 1000) {
      await (await sdk.completeExchange(ex.id)).wait()
    }
  }

  // getFunds takes a subgraph query-vars object, not a positional id.
  const funds = await sdk.getFunds({ fundsFilter: { accountId: seller.id } })
  await (await sdk.withdrawFunds(
    seller.id,
    funds.map(f => f.token.address),
    funds.map(f => f.availableAmount),
  )).wait()
}

main().catch(console.error)
```

## Production hardening

- Persist offer / exchange / withdrawal state to your own DB.
- Use a managed signer (KMS, Vault, Fireblocks, Privy, Turnkey).
- Wrap `completeExchange` calls in a periodic job + monitoring.
- See [Going to production](/concepts/production).

## Related

- [Build → Sellers](/build/sellers)
- [Quickstart → Build a marketplace](/quickstart/marketplace)

---

# Recipe — ERC-20 approve + commit

URL: https://www.bosonprotocol.io/docs/recipes/erc20-commit

> The straightforward two-step path for ERC-20-priced offers.

# Recipe: ERC-20 approve + commit

For ERC-20-priced offers, the buyer must approve the Diamond to pull tokens before committing. This is two transactions; both paid by the buyer.

```ts twoslash
// @noErrors
const sdk = CoreSDK.fromDefaultConfig({
  web3Lib,
  envName: "production",
  configId: "production-137-0",
})

// 1. Approve (idempotent — skip if already approved >= amount). The SDK helper
//    takes the token address and queries against the protocol Diamond by default.
const allowance = await sdk.getExchangeTokenAllowance(USDC)
if (allowance.lt(offer.price)) {
  // First arg is the token address, not the offer id.
  await (await sdk.approveExchangeToken(USDC, offer.price)).wait()
}

// 2. Commit — commitToOffer(offerId, overrides?); buyer is the signer.
const tx = await sdk.commitToOffer(offer.id)
const receipt = await tx.wait()
const exchangeId = sdk.getCommittedExchangeIdFromLogs(receipt.logs)
```

## Tips

- **Approve more than `price`** if you intend to commit to several offers in the same token. Saves one `approve` per commit.
- **Use `MaxUint256`** for "unlimited" approval — common UX pattern. Risk: if your buyer's private key is compromised, attacker can drain the approved amount.
- **For one-shot UX, use the token-auth meta-tx flow** to combine approve + commit in a single signed envelope. See [Recipe → Gas-less commit](./gasless-commit).

## Common reverts

- `InsufficientAllowance` — the buyer didn't approve enough; or they approved the wrong spender (e.g. the voucher contract instead of the Diamond).
- `InsufficientBalance` — the wallet's USDC balance < `price`.
- `OfferVoided` / `OfferHasExpired` — pre-flight your reads to surface this to the user.

## Related

- [Build → Buyers → Commit to an offer](/build/buyers/commit)
- [Troubleshooting → Approve · Permit · Permit2](/troubleshooting/approvals)

---

# Recipe — Gas-less commit (Biconomy)

URL: https://www.bosonprotocol.io/docs/recipes/gasless-commit

> A buyer signs an EIP-712 envelope; Biconomy relays the tx and pays gas.

# Recipe: Gas-less commit (Biconomy)

The buyer never pays gas. They sign an EIP-712 envelope; a Biconomy relayer pays the gas, calls the Diamond's `executeMetaTransaction`, and the commit happens.

For the full signing reference, see [Concepts → Signing & meta-transactions → Boson meta-tx (Biconomy)](/concepts/signing#boson-meta-tx-biconomy).

## Buyer side

```ts twoslash
// @noErrors
import { CoreSDK } from "@bosonprotocol/core-sdk"

const sdk = CoreSDK.fromDefaultConfig({
  web3Lib,
  envName: "production",
  configId: "production-137-0",
})

// The meta-tx helpers live on the top-level SDK (not under a `metaTx` namespace).
//
// 1. Build and sign the meta-tx envelope
const signedMetaTx = await sdk.signMetaTxCommitToOffer({
  buyer: wallet.address,
  offerId,
})

// 2. Relay it through the configured Biconomy endpoint
const txHash = await sdk.relayMetaTransaction(signedMetaTx)
console.log("commit relayed:", txHash)
```

`relayMetaTransaction` calls the configured Biconomy endpoint. The buyer's wallet never broadcasts; only the signature crosses the wire.

## For ERC-20 offers

You also need the token allowance. Two options:

1. **Pre-approve** with a one-time on-chain tx (buyer pays gas once, never again).
2. **Use the token-auth meta-tx flow** to combine approve + commit in one signed envelope:

```ts twoslash
// @noErrors
const signed = await sdk.signMetaTxWithTokenTransferAuthorization({
  functionName: "commitToOffer",
  functionArgs: { buyer, offerId },
  tokenAuth: { type: "ERC3009", /* USDC etc. */ },
})
await sdk.relayForwardedMetaTransaction(signed)
```

See [Concepts → Signing → Token-auth meta-tx](/concepts/signing#token-auth-meta-tx) and [Reference → Core SDK → MetaTx mixin](/reference/core-sdk/meta-tx).

## Common gotchas

- **Biconomy may rate-limit your relayer.** Have a fallback to direct on-chain.
- **The buyer's wallet must support EIP-712 signing.** Most modern wallets do; hardware wallets need firmware updates for some payloads.

## Related

- [Concepts → Signing & meta-transactions](/concepts/signing)
- [Recipes → ERC-20 approve + commit](./erc20-commit)

---

# Recipe — Migrate from legacy v2

URL: https://www.bosonprotocol.io/docs/recipes/migrate-v2

> For teams that integrated against the older Boson v2 docs and want to update.

# Recipe: Migrate from legacy v2

The protocol surface has been stable across v2 → current, but the docs IA, package names, and best practices have shifted. This page maps old concepts to new ones.

## Concept renames

| Old (v2 docs) | Now |
| --- | --- |
| dCommerce ecosystem | _(removed from dev docs; marketing concept)_ |
| Boson Protocol v2 | _(current protocol, just called "Boson")_ |
| dApp | [The Boson dApp](/tooling/dapp) |
| Boson for WooCommerce | [WooCommerce plugin](/tooling/woocommerce) |
| Metaverse toolkit | _(deprecated)_ |
| Commit button widget | [Commit Widget](/widgets/commit) |

## Package map

| Old import | Now |
| --- | --- |
| `@bosonprotocol/core-sdk` | _(same; current version)_ |
| `@bosonprotocol/common` | _(same)_ |
| `@bosonprotocol/ethers-sdk` | _(same)_ |
| `@bosonprotocol/metadata` | _(same)_ |
| `@bosonprotocol/ipfs-storage` | _(same)_ |
| `@bosonprotocol/eth-connect-sdk` | _(unchanged; rarely used)_ |
| Subgraph clients | _(part of `@bosonprotocol/subgraph`; rarely imported directly)_ |

The on-chain Diamond is backwards compatible; existing exchanges from v2 continue to work.

## Doc URL redirects

The new site doesn't host a `/legacy/*` namespace. Old links land on a redirect page; key ones map to:

| Old URL | New URL |
| --- | --- |
| `legacy-docs/learning-resources/quick-start-tutorials/seller-side/selling-on-the-dapp/*` | `/build/sellers/dapp` |
| `legacy-docs/learning-resources/quick-start-tutorials/seller-side/boson-for-woocommerce.md` | `/build/sellers/woocommerce` |
| `legacy-docs/learning-resources/quick-start-tutorials/buyer-side/*` | `/build/buyers/dapp` |
| `legacy-docs/core-concepts/dispute-resolution.md` | `/concepts/dispute-state-machine` |
| `legacy-docs/core-concepts/fees.md` | `/concepts/funds` |
| `legacy-docs/technical-documentation/smart-contracts/architecture.md` | `/concepts/architecture` |

## When you'll have to change code

- **Import paths**: largely unchanged.
- **`configId` adoption**: if your v2 integration used per-chain env vars, switch to a single `configId` per environment.
- **Subgraph indexing lag**: if you weren't calling `waitForGraphNodeIndexing` after writes, start. See [Concepts → Eventing & indexing](/concepts/eventing).
- **Meta-tx**: if you're on Biconomy v1, look at switching to a token-auth meta-tx — fewer steps and cleaner UX.

## Related

- [Tooling overview](/tooling)
- [Going to production](/concepts/production)

---

# Recipe — Mutual dispute resolution

URL: https://www.bosonprotocol.io/docs/recipes/mutual-dispute

> Buyer and seller sign the same EIP-712 payload; whoever submits broadcasts the resolution.

# Recipe: Mutual dispute resolution

When a buyer raises a dispute, the simplest happy-path is mutual resolution: one party signs an EIP-712 payload agreeing on `buyerPercentBasisPoints` (0–10000) and the counterparty submits the on-chain call with that signature.

```ts twoslash
// @noErrors
const buyerPercentBasisPoints = 7000  // 70% to buyer

// 1. Counterparty signs the proposal (here the buyer signs; either side can)
const sig = await buyerSdk.signDisputeResolutionProposal({
  exchangeId,
  buyerPercentBasisPoints,
})
// sig is { r, s, v }

// 2. The other party (seller in this example) submits with the signature
await (await sellerSdk.resolveDispute({
  exchangeId,
  buyerPercentBasisPoints,
  sigR: sig.r,
  sigS: sig.s,
  sigV: sig.v,
})).wait()
```

Only one counterparty signature is required — the submitter is recovered from the calling wallet.

## When negotiation fails

If the parties can't agree, the buyer can escalate to the dispute resolver — see [Buyers → Raise a dispute](/build/buyers/raise-dispute) and [Build → Dispute Resolvers](/build/dispute-resolvers).

## Common gotchas

- **The signed `buyerPercentBasisPoints` must match the value the submitter passes.** Mismatch reverts.
- **The signature must come from the actual buyer or seller wallet** (or a contract via EIP-1271). The Diamond verifies the recovered address against the on-chain entity.
- **The dispute must be in `RESOLVING` state** when the tx submits. If escalation happened in the meantime, the resolution fails.

## Related

- [Concepts → Dispute state machine](/concepts/dispute-state-machine)
- [Concepts → Signing & meta-transactions](/concepts/signing)

---

# Recipe — Threshold-buy agent

URL: https://www.bosonprotocol.io/docs/recipes/threshold-buy-agent

> An autonomous agent that watches Boson offers and commits when the price drops below a threshold.

# Recipe: Threshold-buy agent

An autonomous agent that finds offers matching a criteria, commits to one when the price is right, redeems, and reports.

This combines [Build for AI agents](/agents), the MCP stack, and the idempotency patterns.

```ts twoslash
// @noErrors
import { generateText } from "ai"
import { anthropic } from "@ai-sdk/anthropic"
import { bosonProtocolPlugin } from "@bosonprotocol/agentic-commerce"
import { getOnChainTools } from "@goat-sdk/adapter-vercel-ai"
import { viem } from "@goat-sdk/wallet-viem"

const tools = await getOnChainTools({
  wallet: viem(walletClient),
  plugins: [bosonProtocolPlugin({ url: MCP_URL })],
})

const SYSTEM = `
You are a Boson Protocol buyer agent on Base Sepolia.
You buy items matching the user's criteria — but only if the price is below the threshold.

Rules:
- Never commit twice for the same goal. Persist the result to your memory store.
- Always wait for indexing before reading state you just wrote.
- On any error you can't classify, abort and report.
`

async function tryBuyOnce(goal: { keyword: string; maxPriceUSDC: bigint }) {
  if (await alreadyBoughtFor(goal)) return
  await generateText({
    model: anthropic("claude-sonnet-4-6"),
    tools,
    maxSteps: 12,
    system: SYSTEM,
    prompt: `Find an offer matching "${goal.keyword}" priced ≤ ${goal.maxPriceUSDC} USDC base units. If you find one, commit. Otherwise report no match.`,
  })
}

// Cron loop
setInterval(() => {
  tryBuyOnce({ keyword: "GPU", maxPriceUSDC: 500_000_000n }).catch(console.error)
}, 5 * 60_000)
```

## Required state

The agent persists per-goal idempotency keys, so re-runs after crashes don't double-buy. See [Build for AI agents → Idempotency & retry](/agents/idempotency) and [Memory & state](/agents/memory).

## Production hardening

- Wrap the agent in a circuit breaker — pause if the wallet balance drops or if reverts spike.
- Cap max-spend per day at the wallet level (use a session key on a Safe).
- Log every tool call with a correlation ID.
- See [Going to production](/concepts/production).

## Related

- [Quickstart → Buy with an AI agent](/quickstart/ai-agent-buyer)
- [Build for AI agents](/agents)

---

# Recipe — Token-gated launch

URL: https://www.bosonprotocol.io/docs/recipes/token-gated

> Restrict who can commit to your offer based on token holdings.

# Recipe: Token-gated launch

A seller restricts an offer to holders of a specific ERC-20, ERC-721, or ERC-1155.

```ts twoslash
// @noErrors
// Holders of >= 1 of NFT 0xabc... can buy, once each
await sdk.createOfferWithCondition({
  offer: {
    price: "1000000",
    quantityAvailable: "100",
    exchangeToken: USDC_ADDRESS,
    metadataUri,
    metadataHash,
    // … dates, dispute resolver, agent …
  },
  condition: {
    method: 1,                  // 1 = Threshold
    tokenType: 1,               // 0=ERC20, 1=ERC721, 2=ERC1155
    tokenAddress: "0xabc…",
    tokenId: "0",               // unused for threshold-721 (any token in collection)
    threshold: "1",             // hold at least 1
    maxCommits: "1",            // each holder can buy once
    gating: 0,                  // 0=PerAddress, 1=PerTokenId
  },
})
```

## Variations

- **Per-tokenId drops** — use `gating: 1` and each `tokenId` can be used `maxCommits` times.
- **Open after threshold** — set `threshold` to e.g. `5` to require holding 5+ NFTs.
- **ERC-20 thresholds** — pass `tokenType: 0` and threshold in token base units.

## Caveats

- The Diamond reads the buyer's token balance at commit time. **Flash-loaning the gating token won't work** for ERC-721 (balance is checked atomically inside the tx), but the buyer could buy + commit + sell in one bundle. For very high-value drops, consider a snapshot.
- Condition enum naming has drifted in older SDK versions (`SpecificToken` ↔ `TokenRange`). Pin SDK version.

## Related

- [Build → Marketplace operators → Token-gated launches](/build/marketplace/token-gated)
- [Reference → Core SDK → Groups mixin](/reference/core-sdk/groups)

---

# Recipe — Webhook server for state changes

URL: https://www.bosonprotocol.io/docs/recipes/webhook-server

> A reorg-safe, idempotent event listener that posts Boson state changes to your backend.

# Recipe: Webhook server for state changes

Listen to the Diamond's events on your target chains, dedupe across reorgs, and POST to your fulfillment system.

```ts twoslash
// @noErrors
import express from "express"
import { ethers } from "ethers"
// There is no ProtocolDiamondABI export — combine per-facet ABIs from
// @bosonprotocol/common/dist/cjs/abis/*.json. Use getConfigFromConfigId, not
// getDefaultConfig.
import { getConfigFromConfigId } from "@bosonprotocol/common"
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"
import disputeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonDisputeHandler.json"
import { Pool } from "pg"

const db = new Pool({ connectionString: process.env.DATABASE_URL })
const config = getConfigFromConfigId("production-137-0")
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL)
const diamond = new ethers.Contract(
  config.contracts.protocolDiamond,
  [...offerAbi, ...exchangeAbi, ...disputeAbi],
  provider,
)

const CONFIRMATIONS = 3

async function processEvent(evt: ethers.Event) {
  const dedupeKey = `${evt.transactionHash}:${evt.logIndex}`
  const { rowCount } = await db.query(
    "INSERT INTO processed_events (key) VALUES ($1) ON CONFLICT DO NOTHING",
    [dedupeKey],
  )
  if (rowCount === 0) return // already processed

  // Wait for confirmations
  const confirmations = await provider.getTransactionReceipt(evt.transactionHash)
    .then(r => provider.getBlockNumber().then(head => head - r.blockNumber + 1))
  if (confirmations < CONFIRMATIONS) {
    await db.query("DELETE FROM processed_events WHERE key=$1", [dedupeKey])
    return // try again on next pass
  }

  // Forward to your backend
  await fetch(process.env.BACKEND_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      event: evt.event,
      args: evt.args,
      txHash: evt.transactionHash,
      logIndex: evt.logIndex,
      blockNumber: evt.blockNumber,
    }),
  })
}

for (const event of ["BuyerCommitted", "VoucherRedeemed", "ExchangeCompleted", "DisputeRaised"]) {
  diamond.on(event, (...args) => processEvent(args.at(-1)))
}

// Health endpoint
const app = express()
app.get("/health", (_, res) => res.json({ ok: true }))
app.listen(3000)
```

## Schema

```sql
CREATE TABLE processed_events (
  key TEXT PRIMARY KEY,
  processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

## Catch-up on restart

For a long-running listener, use a `last_block_number` checkpoint:

```ts twoslash
// @noErrors
const last = await db.query("SELECT last_block FROM listener_state")
const events = await diamond.queryFilter("*", last + 1, "latest")
for (const evt of events) await processEvent(evt)
```

## Production hardening

- **Alert on subgraph staleness** alongside this — your event listener might miss events under RPC instability; the subgraph is the fallback.
- **HMAC-sign the POST body** before sending to your backend.
- **Retry with exponential backoff** on backend failures.

## Related

- [Concepts → Eventing & indexing](/concepts/eventing)
- [Build → Marketplace operators → Webhooks & events](/build/marketplace/webhooks)

---

# Recipe — Sell via WooCommerce

URL: https://www.bosonprotocol.io/docs/recipes/woocommerce

> Install the Boson for WooCommerce plugin and start selling.

# Recipe: Sell via WooCommerce

A no-code path for sellers who already run a WordPress / WooCommerce store. Detailed walkthrough lives at [Build → Sellers → Sell via WooCommerce](/build/sellers/woocommerce).

## Quick steps

1. Install the **Boson for WooCommerce** plugin from the WordPress plugin marketplace.
2. Connect a wallet (the plugin uses WalletConnect).
3. Run the setup wizard to create your Boson seller account.
4. In the plugin admin, map WooCommerce products → Boson offers.
5. Pick a dispute resolver from the dropdown (chain-dependent; see [Build → Dispute Resolvers](/build/dispute-resolvers)).
6. (Optional) Configure token-gating per product.
7. Save. Your storefront's checkout is now Boson-powered.

## What buyers see

When a buyer reaches checkout, the plugin renders the [Boson Commit Widget](/widgets/commit) configured for that product. Commitment lands as a WooCommerce order with status "Boson committed".

## After redemption

`VoucherRedeemed` events flip the WooCommerce order status to "Boson redeemed", which triggers your normal WooCommerce fulfillment flow (shipping, status emails, etc.).

## Related

- [Tooling → WooCommerce plugin](/tooling/woocommerce)
- [Build → Sellers → Sell via WooCommerce](/build/sellers/woocommerce)

---

# Recipe — x402 buyer paying for a digital asset

URL: https://www.bosonprotocol.io/docs/recipes/x402-buyer

> A buyer client that makes a paid HTTP request and receives the digital asset inline.

# Recipe: x402 buyer paying for a digital asset

```ts twoslash
// @noErrors
import { createX402bClientFetch } from "@bosonprotocol/x402-client-fetch"
import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.BUYER_PRIVATE_KEY!)
const fetchWithPayment = createX402bClientFetch({
  signer: wallet,
  preferredTokenAuth: ["ERC3009", "Permit2", "Permit"],
  preferredFulfillment: ["inline", "ipfsPointer"],
  maxValue: { token: USDC_ADDRESS, amount: 5_000_000n },  // ≤ 5 USDC
})

const res = await fetchWithPayment("https://api.example.com/premium-data")

if (!res.ok) {
  console.error("payment failed:", await res.text())
  process.exit(1)
}

const asset = await res.json()
console.log("got it:", asset)
```

## What just happened

1. Plain GET → server returned 402 with a Boson escrow option.
2. Client signed a meta-tx + ERC-3009 token authorization.
3. Re-issued with `X-PAYMENT` header.
4. Server forwarded to the facilitator → on-chain commit → atomic redeem.
5. Server returned the asset inline.

## Common gotchas

- **No matching token-auth** — if the server advertises only `approve` and your client only accepts signed authorizations, the call fails. Loosen preferences or fall back to a manual approve.
- **Server's facilitator is down** — you'll get 503 from the server. Retry with backoff; ultimately, you may need to find a different seller.

## Related

- [Quickstart → Accept x402 escrow payments](/quickstart/x402-server)
- [Build with x402 → Buyer side](/x402/buyer)
- [Recipe → x402 server email-fulfillment](./x402-email)

---

# Recipe — x402 server email-fulfillment

URL: https://www.bosonprotocol.io/docs/recipes/x402-email

> An x402b server that delivers digital codes by email after on-chain settlement.

# Recipe: x402 server email-fulfillment

A server protecting a "get me a license key" endpoint. After on-chain settlement, it emails the buyer.

```ts twoslash
// @noErrors
import express from "express"
import { createX402bServerExpress } from "@bosonprotocol/x402-server-express"
import { ChannelRegistry, type FulfillmentChannel } from "@bosonprotocol/x402-fulfillment"
import { Resend } from "resend"
import { ethers } from "ethers"

const resend = new Resend(process.env.RESEND_API_KEY)
const wallet = new ethers.Wallet(process.env.SELLER_PRIVATE_KEY!)

const emailChannel: FulfillmentChannel = {
  id: "email",
  async fulfill({ buyer, exchangeId, deliveryInfo }) {
    const licenseKey = await mintLicenseKey(exchangeId)
    await resend.emails.send({
      from: "licenses@example.com",
      to: deliveryInfo!.email,
      subject: "Your license key",
      text: `Thanks! Your key: ${licenseKey}`,
    })
  },
}

const x402 = createX402bServerExpress({
  network: "polygon",
  chainId: 137,
  escrow: {
    configId: "production-137-0",
    sellerId: "12",
    productUuid: "ec00f1a5-2c96-4d22-9d80-2a7c12345678",
    fulfillment: { channels: ["email"] },
  },
  signer: wallet,
  facilitator: { url: "https://facilitator.bosonprotocol.io" },
  channelRegistry: new ChannelRegistry([emailChannel]),
})

const app = express()
app.get("/api/license", x402.middleware(), async (_, res) => {
  // Middleware already fulfilled via the email channel.
  res.json({ ok: true, exchangeId: req.x402!.exchangeId })
})

app.listen(3000)
```

## Buyer side

The buyer client supplies their email in the `X-PAYMENT` envelope:

```ts twoslash
// @noErrors
await fetchWithPayment("https://api.example.com/license", {
  headers: {
    "x402-fulfillment": JSON.stringify({ channel: "email", email: "buyer@example.com" }),
  },
})
```

## Idempotency

Persist `(exchangeId) -> emailedAt` in your DB. If a reorg or replay re-fires the redemption event, don't re-email.

## Related

- [Build with x402 → Fulfillment channels](/x402/fulfillment)
- [Concepts → Fulfillment channels](/concepts/fulfillment)

---

# Troubleshooting

URL: https://www.bosonprotocol.io/docs/troubleshooting

> Things that go wrong, what they mean, and what to do.

# Troubleshooting

A page per common class of failure. Each page has the symptoms, the cause, and the fix.

## Pages

- [Subgraph indexing lag](./troubleshooting/indexing-lag) — _the most common footgun_.
- [Reverts & error codes](./troubleshooting/reverts) — decoding on-chain reverts.
- [Signature mismatches](./troubleshooting/signatures) — EIP-712 didn't recover.
- [Approve · Permit · Permit2](./troubleshooting/approvals) — ERC-20 authorization gotchas.
- [Metadata validation](./troubleshooting/metadata) — `validate_metadata` errors and how to read them.
- [Gas estimation](./troubleshooting/gas) — per-chain quirks.
- [FAQ](./troubleshooting/faq) — questions that don't fit elsewhere.

## When to ask for help

If you've checked the relevant page and your issue persists:

1. Reproduce on staging.
2. Capture: SDK version, `configId`, exact tool call args (redact keys), full error.
3. Post in the [Boson Discord](https://discord.gg/QSdtKRaap6) or open an issue on the relevant repo.

---

# Troubleshooting — Approve · Permit · Permit2

URL: https://www.bosonprotocol.io/docs/troubleshooting/approvals

> ERC-20 authorization gotchas across the four token-auth strategies.

# Approve · Permit · Permit2

## Symptom

You call `commitToOffer` on an ERC-20-priced offer and the tx reverts with `InsufficientAllowance`, `ERC20: insufficient allowance`, or a similar transfer error.

## Causes

### 1. Spender mismatch

You approved the wrong contract. The spender must be the **Diamond**, not the voucher (rNFT) contract.

```ts twoslash
// @noErrors
// WRONG
await token.approve(voucherContract, amount)

// RIGHT
await token.approve(diamondAddress, amount)

// EVEN BETTER (handled by the SDK)
await sdk.approveExchangeToken(offerId, amount)
```

### 2. Amount too small

You approved `price` but didn't account for protocol/agent fees, or the offer has a buyer deposit.

For a typical offer:
- Buyer pays `offer.price`.
- Approval must be ≥ `offer.price`.

For offers with non-zero buyer deposit:
- Buyer pays `offer.price + offer.buyerCancelPenalty`... no, wait: `buyerCancelPenalty` only matters on cancel. The amount transferred at commit is `offer.price`.

Approve a comfortable surplus (e.g. `offer.price * 2`) to avoid this.

### 3. EIP-2612 Permit vs. ERC-3009 confusion

USDC uses **ERC-3009** (`receiveWithAuthorization`), not EIP-2612 Permit. If you sign a Permit and send it for USDC, it'll either revert or be silently ignored.

Use:
- `ERC3009` for USDC, EURC, and other ERC-3009-supporting tokens.
- `Permit` (EIP-2612) for DAI, USDS, and others.
- `Permit2` as a universal fallback.

See [Concepts → Signing → Token-auth meta-tx](/concepts/signing#token-auth-meta-tx) and [x402 → Token-auth strategies](/x402/token-auth).

### 4. Permit2 not pre-approved

Permit2 requires a one-time approval of the Permit2 contract itself for each token. Once that's done, per-use authorizations are signed envelopes (no on-chain tx). If your buyer hasn't pre-approved Permit2 for the token, the per-use authorization will fail.

```ts twoslash
// @noErrors
const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3"
await token.approve(PERMIT2, ethers.constants.MaxUint256)
// now Permit2-style signed envelopes work
```

### 5. ERC-20 race conditions

Some tokens (USDT, classic implementations) refuse to update allowance from a non-zero value. You must approve `0` first, then the new amount:

```ts twoslash
// @noErrors
await token.approve(spender, 0).then(t => t.wait())
await token.approve(spender, amount).then(t => t.wait())
```

The SDK's `approveExchangeToken` handles this for known-problematic tokens.

## Fix summary

For 95 % of cases:

```ts twoslash
// @noErrors
await (await sdk.approveExchangeToken(offerId, /* amount */ offer.price)).wait()
await (await sdk.commitToOffer(buyer, offerId)).wait()
```

For gas-optimized UX:

```ts twoslash
// @noErrors
const signed = await sdk.metaTx.signMetaTxWithTokenTransferAuthorization({
  functionName: "commitToOffer",
  functionArgs: { buyer, offerId },
  tokenAuth: { type: "ERC3009" }, // for USDC
})
await sdk.metaTx.relayForwardedMetaTransaction(signed)
```

## Related

- [Concepts → Signing & meta-transactions](/concepts/signing)
- [Build → Buyers → Commit to an offer](/build/buyers/commit)
- [Recipes → ERC-20 approve + commit](/recipes/erc20-commit)

---

# Troubleshooting — FAQ

URL: https://www.bosonprotocol.io/docs/troubleshooting/faq

> Questions that don't fit elsewhere.

# FAQ

## "Why is my transaction unsigned?"

The MCP server **never signs**. State-changing tools return an unsigned tx; your code signs and broadcasts. See [Build for AI agents → The 3-step signing pattern](/agents/signing).

## "How long is the dispute window?"

Set per-offer via `OfferDurations.disputePeriod`. It starts at `REDEEMED`. Typical: 7–30 days.

## "Can a seller and buyer be the same wallet?"

Yes. The protocol treats them as distinct entities even if they share an address. Common for testing.

## "What happens if the voucher window expires before I redeem?"

The exchange transitions to `EXPIRED`. The buyer recovers `price`; the seller keeps `sellerDeposit`. Either party can call `expireVoucher`.

## "Can I update an offer after publishing?"

No. Offers are immutable. Void and re-create.

## "How do I cancel an exchange after I commit?"

`cancelVoucher(exchangeId)`. You pay `buyerCancelPenalty` to the seller; rest is refunded.

## "Are gas fees included in the listed price?"

No. Listed `price` is what the seller receives (minus protocol/agent fees). The buyer pays gas separately (unless using meta-tx). See [Concepts → Funds, escrow & payouts](/concepts/funds).

## "Can a smart account commit?"

Yes. The Diamond accepts EIP-1271 signatures. Safe, ERC-4337 accounts, and other contract wallets work.

## "What's the difference between `cancelVoucher` and `revokeVoucher`?"

`cancelVoucher` is buyer-initiated (penalty paid to seller). `revokeVoucher` is seller-initiated (seller deposit forfeited to buyer). Both end the exchange.

## "What's an `agentId` of `0`?"

No protocol agent attached. The protocol fee goes entirely to Boson; no third-party cut. Set a real `agentId` only if you have a registered protocol agent.

## "How do I find my seller ID?"

`sdk.getSellersByAddress(yourAddress)` or `mcp.getSellersByAddress({ wallet: yourAddress })`.

## "Does Boson work on EVM L3s / app chains?"

If the chain has a Diamond deployment in the address files, yes. If not, no. Adding a new chain is a config + deployment process; open an issue.

## "Can I run Boson against a forked node?"

Yes. Deploy the contracts (use `scripts/deploy-suite.js` in `boson-protocol-contracts`) and use a `local-*` ConfigId.

## "Where do I report a security issue?"

Email `security@bosonprotocol.io` per the [boson-protocol-contracts security policy](https://github.com/bosonprotocol/boson-protocol-contracts/blob/main/SECURITY.md).

---

# Troubleshooting — Gas estimation

URL: https://www.bosonprotocol.io/docs/troubleshooting/gas

> Per-chain gas quirks and how to handle them.

# Gas estimation

## Symptom

Tx reverts with "out of gas" despite estimation; or estimation succeeds but the tx fails on certain chains.

## Causes

### Polygon's gas dynamics

Polygon's L1 fee and base fee fluctuate fast; estimation captured at time _t_ may be 30 % low at time _t+1_. Bump the gas limit ~20–30 % above the SDK's estimate for write-heavy paths.

### Base / Optimism / Arbitrum L1 data fee

L2s have two gas components: L2 execution gas + L1 data fee. The L1 data fee is computed against the call data size; very large calldata (e.g. heavy metadata in a meta-tx) can spike it.

Use viem / ethers' `estimateGas` and bump cautiously; over-estimating doesn't waste much on L2 (you only pay for what you use), but reverts cost the full reserved amount.

### Diamond's facet routing overhead

Diamond calls have a small constant overhead (~3-5k gas) for the routing. Inside an `OrchestrationHandlerFacet` call that batches multiple operations, this overhead is paid once — but the inner operations each touch many storage slots.

`createOfferAndCommitAndRedeem` is one of the heaviest paths. Reserve generously.

### MetaTx envelope overhead

Meta-tx adds signature verification + nonce bumping (~30k gas) on top of the inner call. If your buyer client's estimator forgets to include this, the relayed tx reverts.

The SDK's `relayMetaTransaction` accounts for this; if you build the envelope yourself, add 50k gas as a safety margin.

## Fix

### Always wait and bump

```ts twoslash
// @noErrors
const estimate = await sdk.estimateGas.commitToOffer(buyer, offerId)
const tx = await sdk.commitToOffer(buyer, offerId, {
  gasLimit: estimate.mul(120).div(100), // +20%
})
```

### Watch chain congestion

Use a paid RPC for production. Free-tier RPCs (default Alchemy demo, public RPCs) throttle aggressively and give stale gas estimates under load.

### Monitor on a dashboard

Track median gas per tx type per chain. Alert when median jumps > 2x — usually a chain-congestion event you'll want to ride out, not retry into.

## Related

- [Concepts → Going to production](/concepts/production)
- [Build for AI agents → Wallet patterns](/agents/wallets)

---

# Troubleshooting — Subgraph indexing lag

URL: https://www.bosonprotocol.io/docs/troubleshooting/indexing-lag

> The number-one source of "the protocol is broken" reports. It isn't broken; it's lagging.

# Subgraph indexing lag

## Symptom

You just performed a write (commit, redeem, create offer, …), then immediately read state from the SDK or MCP, and got stale data — your new exchange isn't there, your new offer doesn't show up, etc.

## Cause

The Boson subgraph (a Graph Protocol deployment) processes on-chain events asynchronously. It typically lags 1–3 blocks behind the chain head — sometimes more under load.

When you call `sdk.getOffers()`, `mcp.getExchanges()`, or any SDK / MCP read method that hits the subgraph, you're querying its current view — not the chain head.

## Fix

After every write, call:

```ts twoslash
// @noErrors
const tx = await sdk.commitToOffer(buyer, offerId)
const receipt = await tx.wait()
await sdk.waitForGraphNodeIndexing(receipt.blockNumber)
// safe to read now
```

`waitForGraphNodeIndexing(blockNumber)` polls the subgraph's `_meta { block { number } }` until it catches up to your tx's block, or until the timeout (default ~30 s).

## For agents

Make this a mandatory step in your loop. See [Build for AI agents → Idempotency & retry](/agents/idempotency).

## Alternative: read from RPC

If you need real-time state (e.g. "is the offer sold out?"), read directly from the Diamond:

```ts twoslash
// @noErrors
// Build the Diamond contract yourself — there's no sdk.getDiamondContract() helper.
import { getConfigFromConfigId } from "@bosonprotocol/common"
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import { ethers } from "ethers"

const config = getConfigFromConfigId(CONFIG_ID)
const diamond = new ethers.Contract(config.contracts.protocolDiamond, offerAbi, provider)
const remaining = await diamond.getAvailableQuantity(offerId)
```

RPC reads are zero-lag but have lower throughput and no convenience joins.

## When the lag persists

If `waitForGraphNodeIndexing` _times out_, the subgraph is genuinely behind. Check its health:

```graphql
{ _meta { block { number } hasIndexingErrors } }
```

If `hasIndexingErrors == true`, report it in [Boson Discord](https://discord.gg/QSdtKRaap6).

## Related

- [Concepts → Eventing & indexing](/concepts/eventing)
- [Build for AI agents → Idempotency & retry](/agents/idempotency)

---

# Troubleshooting — Metadata validation

URL: https://www.bosonprotocol.io/docs/troubleshooting/metadata

> validate_metadata errors and what to do about them.

# Metadata validation

## Symptom

```
{
  "valid": false,
  "errors": [
    { "path": "/productV1/title", "message": "required" },
    { "path": "/productV1/images/0/url", "message": "must match format" }
  ]
}
```

Or the on-chain `createOffer` reverts with an opaque "metadata hash mismatch" or similar.

## Causes

### 1. Schema mismatch

You're using `PRODUCT_V1` fields with a `BASE` schema (or vice versa). Check `type` on the top-level metadata object.

### 2. Required field missing

The error `path` tells you where. Look at the corresponding zod schema in `@bosonprotocol/metadata` — every field is required unless explicitly optional.

### 3. URL format issues

Image / file URLs must be:
- HTTPS (`https://...`), or
- IPFS (`ipfs://Qm...`).

`http://` is rejected. Some clients also reject data URLs and relative paths.

### 4. UUID format

`uuid` must be a v4 UUID string (the `crypto.randomUUID()` output). Random strings won't pass.

### 5. Length overflow

Metadata is capped at **20 MB**. If you embed images in `dataUrl` form, you'll blow this. Use CDN URLs or IPFS references for images.

### 6. Metadata-hash mismatch on-chain

If `validate_metadata` passes but `createOffer` reverts, your `metadataHash` doesn't match what `metadataUri` resolves to. The simplest fix is to derive the hash from the URI you got back from `storeMetadata` — the IPFS CID is the hash:

```ts twoslash
// @noErrors
const metadataUri = await sdk.storeMetadata(metadata)
const metadataHash = metadataUri.replace(/^ipfs:\/\//, "")
// pass both into createOffer
```

## Debugging

Always run `validate_metadata` _before_ `storeMetadata`. Iterate until clean, then pin. This saves wasted IPFS writes.

```ts twoslash
// @noErrors
const { valid, errors } = await sdk.validateMetadata(metadata)
if (!valid) { console.error(errors); process.exit(1) }
const uri = await sdk.storeMetadata(metadata)
```

## Schema source

- [`@bosonprotocol/metadata/src`](https://github.com/bosonprotocol/core-components/tree/main/packages/metadata/src)
- [Reference → Metadata schemas](/reference/metadata)

## Related

- [Concepts → The metadata pipeline](/concepts/metadata)
- [Build → Sellers → Publish an offer](/build/sellers/publish-offer)

---

# Troubleshooting — Reverts & error codes

URL: https://www.bosonprotocol.io/docs/troubleshooting/reverts

> Decoding "execution reverted" into something actionable.

# Reverts & error codes

## Symptom

```
Error: execution reverted (unknown custom error)
```

or with a selector like `0x82b42900`.

## Cause

The Diamond's facets emit **custom errors** (Solidity 0.8.4+). The 4-byte selector identifies which error; without the ABI you can't decode it.

## Fix

### Use `sdk.parseError`

```ts twoslash
// @noErrors
try {
  await sdk.commitToOffer(buyer, offerId)
} catch (err) {
  const parsed = sdk.parseError(err)
  console.error(parsed) // { code: "OfferVoided", name: "OfferVoided", args: { offerId: "123" } }
}
```

### Or decode against the merged ABI

```ts twoslash
// @noErrors
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"
import disputeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonDisputeHandler.json"
import fundsAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonFundsHandler.json"
import priceAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonPriceDiscoveryHandler.json"
import { ethers } from "ethers"

const iface = new ethers.utils.Interface([...offerAbi, ...exchangeAbi, ...disputeAbi, ...fundsAbi, ...priceAbi])
try {
  iface.parseError(err.data ?? err.error?.data)
} catch { /* not a known custom error */ }
```

## Common errors and their meaning

| Error | Cause | Fix |
| --- | --- | --- |
| `RegionPaused` | Protocol region paused | Wait; check `pausedRegions()` |
| `OfferHasExpired` | `validUntilDate < now` | Use a different offer |
| `OfferVoided` | Seller voided the offer | Use a different offer |
| `QuantityExceeded` | Sold out | Wait or try a variant |
| `CannotCommit` | Token-gating condition not met | Acquire the gating token |
| `ExchangeIsNotInRedeemableState` | Wrong state or window closed | Check exchange state |
| `VoucherNotExpired` | Tried to expire voucher early | Wait |
| `DisputeNotEscalatable` | Dispute not yet eligible to escalate | Wait for resolution window |
| `InvalidNonce` | Meta-tx nonce already used | Re-fetch nonce, re-sign |
| `SignatureValidationFailed` | EIP-712 didn't recover to expected signer | See [Signature mismatches](./signatures) |
| `InsufficientValueReceived` | `msg.value` < price for native offer | Send more |
| `InsufficientAllowance` | ERC-20 not approved | Approve first |

For the full catalog, see [Reference → Contracts → Custom errors](/reference/contracts/errors).

## Logging

Always log the parsed error code, not just the message. The code is grep-able; the message is wrapped by RPC providers and varies.

## Related

- [Reference → Contracts → Custom errors](/reference/contracts/errors)
- [Build for AI agents → Idempotency & retry](/agents/idempotency)

---

# Troubleshooting — Signature mismatches

URL: https://www.bosonprotocol.io/docs/troubleshooting/signatures

> When EIP-712 signatures don't recover to the expected signer.

# Signature mismatches

## Symptom

A meta-tx or mutual-resolve call reverts with `SignatureValidationFailed` (or "recovered address doesn't match expected").

## Causes (in rough order of likelihood)

1. **Wrong typed-data structure.** Hand-built typed-data drifts from the on-chain verifier.
2. **Wrong domain separator.** Chain ID or verifying-contract mismatch.
3. **Hardware wallet quirk.** Some HW wallets corrupt long typed-data; check firmware.
4. **EIP-1271 smart-account signature** when the verifier expects EOA, or vice versa.
5. **Stale nonce.** Signature for nonce N submitted at nonce N+1.
6. **Wrong signer.** Someone other than the expected user signed.

## Fix

### Always use the SDK / MCP signing helpers

```ts twoslash
// @noErrors
// CORRECT
const signed = await sdk.metaTx.signMetaTxCommitToOffer({ buyer, offerId })

// WRONG: do not hand-build
const signed = await wallet._signTypedData(domain, types, message) // domain drifts!
```

The SDK builds the typed-data identically to the on-chain verifier. Hand-built typed-data is the #1 cause of mismatches.

### Check the domain

The EIP-712 `domain` must match the on-chain verifier exactly:

```ts
{
  name: "BosonProtocolDiamond",
  version: "V2",
  chainId: <actual chain id>,
  verifyingContract: <Diamond address for this configId>,
}
```

A `chainId` mismatch causes recovered addresses to be junk. If you're on Polygon production, the chainId must be 137 — not 1, not 80002.

### For smart accounts

The Diamond accepts EIP-1271 signatures. If your buyer is a Safe, the signing flow is:

1. Safe owners sign the inner data offline.
2. Combine into a Safe signature blob.
3. The blob is what gets passed as the meta-tx signature.

The Diamond calls `IERC1271.isValidSignature(hash, sig)` on the buyer address. Make sure your Safe is deployed at the address you're using.

### Nonce check

```ts twoslash
// @noErrors
const nonce = await diamond.getNonce(userAddress)
// ensure the signature you produce uses exactly this nonce
```

## Debugging

If `SignatureValidationFailed` is intermittent under concurrency, you have a nonce race. Serialize signing or generate fresh nonces.

## Related

- [Concepts → Signing & meta-transactions](/concepts/signing)
- [Reference → Core SDK → MetaTx mixin](/reference/core-sdk/meta-tx)

---

# Glossary

URL: https://www.bosonprotocol.io/docs/glossary

> Canonical definitions for Boson Protocol terminology.

# Glossary

Every protocol term used in these docs is defined here, exactly once. If you see a term in another page that isn't linked, that's a bug — open an issue.

The rule: **one canonical name per concept**. We use the name on the left of each entry; alternate names (right of em-dash) are listed only so search finds them.

## A

### Agent (protocol role) — _aka dACP agent, protocol agent_
A registered entity that earns a fee for facilitating an exchange. **Distinct from AI agent.** Configured on an offer at creation time; the agent's wallet receives a percentage cut on completion. See [Roles](/concepts/roles#agent).

### Agent (AI) — _aka autonomous agent, agent_
An AI program (Vercel AI · LangChain · Claude SDK · etc.) that calls Boson via MCP or the SDK. Never use "agent" without a qualifier in the same paragraph where the protocol role appears.

### Atomic commit-and-redeem
A single transaction that both commits to an offer and redeems the voucher. Used for instant digital deliveries.

## B

### Buyer
The protocol entity that commits to an offer. Created on-chain via `createBuyer()`. One wallet can be both a buyer and a seller.

### Bundle
An offer that ships multiple items together (e.g. a digital license + a physical t-shirt). Modeled by the `BUNDLE` metadata schema.

## C

### Commit
The act of a buyer accepting an offer. Burns the buyer's deposit into escrow, issues an rNFT to the buyer, and transitions the new exchange to `COMMITTED`.

### ConfigId
A string that uniquely identifies a protocol deployment: `${envName}-${chainId}-${index}` — e.g. `production-137-0` (Polygon mainnet, index 0) or `staging-84532-0` (Base Sepolia). Every SDK, MCP tool, and widget call takes one. Full list in [Networks & ConfigIds](/concepts/networks-and-configids).

### Core SDK
The TypeScript SDK at `@bosonprotocol/core-sdk`. The primary developer entry point for human-facing apps. See [Tooling → Core SDK](/tooling/core-sdk).

## D

### dACP — _Decentralized Agentic Commerce Protocol_
Boson Protocol's product-tier name, emphasizing the agent-commerce thesis. In these docs, "Boson" and "dACP" are interchangeable; we prefer "Boson".

### Diamond
The on-chain entry point. An EIP-2535 proxy aggregating 21 handler facets (offers, exchanges, disputes, funds, …). All write paths go through it. See [Architecture](/concepts/architecture).

### Dispute resolver — _DR_
A third party registered on-chain to arbitrate disputed exchanges. Can be a centralised entity, a multisig, or an external decentralised arbitration system (e.g. [Kleros](https://kleros.io)).

## E

### EIP-712 typed-data
Signed structured data, used by Boson for meta-transactions and for `FullOffer` signing. See [Signing & meta-transactions](/concepts/signing).

### Escalation
A dispute that has run out the resolution window without mutual agreement is escalated to the dispute resolver for a binding decision.

### Exchange
A specific, on-chain instance of a buyer's commitment to a seller's offer. Has a numeric `exchangeId`, a state, and links to a single buyer, seller, and offer. The unit of state in Boson. See [Exchange state machine](/concepts/exchange-state-machine).

## F

### Facet
One of the 21 handler contracts that make up the Diamond. Each facet groups related entry points (e.g. `OfferHandlerFacet`, `ExchangeHandlerFacet`). See [Reference → Contracts → Diamond facets](/reference/contracts/facets).

### Facilitator
In the x402 stack, a server that relays signed meta-transactions to the Diamond on behalf of buyers. Optional. See [x402 → Facilitator](/x402/facilitator).

### Fermion — _high-value asset module_
A module of the protocol for premium / fractionalized assets, with additional roles (verifier, custodian). Surfaced as a separate MCP server. See [Build for AI agents → High-value asset module](/agents/fermion).

### FullOffer
A signed EIP-712 payload representing an offer that hasn't yet been written on-chain. Used for non-listed (private / EIP-712) flows and for x402.

## G

### GOAT SDK plugin
A drop-in plugin for the [GOAT SDK](https://github.com/goat-sdk/goat) that auto-registers all 56 Boson MCP tools for use with Vercel AI, LangChain, Anthropic SDK, etc. See [Tooling → MCP](/tooling/mcp).

## I

### Indexing lag
The 1–3 block delay between a transaction being mined and the subgraph reflecting its effects. The number-one footgun in agent code. Handle with `coreSdk.waitForGraphNodeIndexing(blockNumber)`. See [Eventing & indexing](/concepts/eventing) and [Troubleshooting → Indexing lag](/troubleshooting/indexing-lag).

## M

### MCP — _Model Context Protocol_
Anthropic's open protocol for exposing tools to LLM agents. Boson ships a hosted MCP server at `boson-mcp-server-{staging,production}-…run.app/mcp` with ~56 tools.

### Meta-transaction
A transaction signed by one party (the user) but submitted on-chain by another (a relayer or facilitator). Enables gas-less UX. Boson supports direct meta-tx, Biconomy-relayed, and token-auth variants. See [Signing & meta-transactions](/concepts/signing).

### Metadata
Off-chain JSON describing an offer (title, description, images, attributes, contractual agreement). Pinned to IPFS; the URI is stored on-chain. Schemas: `PRODUCT_V1`, `BUNDLE`, `BASE`. See [The metadata pipeline](/concepts/metadata).

## O

### Offer
The seller's listing. Includes price, deposit, validity window, dispute resolver, metadata URI, and (optionally) a token-gating condition. Lives on-chain after `createOffer()`.

### Orchestration
A family of facets that atomically combine multiple operations (e.g. `createOfferAndCommit()`, `createOfferCommitAndRedeem()`). Used to reduce round-trips and to enable atomic commit-and-redeem.

## P

### Permit, Permit2, ERC-3009
Three on-chain token-authorization standards, all supported in Boson meta-transactions via the token-auth meta-tx flow. See [Signing & meta-transactions](/concepts/signing).

### Pre-minted voucher
A voucher rNFT minted before any buyer commits. Used for limited drops.

### PRODUCT_V1
The canonical metadata schema for physical products. Distinct from `BASE` (minimum) and `BUNDLE`. See [Reference → Metadata schemas](/reference/metadata).

## R

### Redemption
The buyer's act of claiming the goods or services. Transitions the exchange from `COMMITTED` to `REDEEMED` and starts the dispute window.

### rNFT — _redemption NFT, voucher_
The ERC-721 token minted to the buyer's wallet when they commit. Burned on redemption. _Within these docs, prefer "voucher" in user-facing copy and "rNFT" only when discussing on-chain mechanics._

### Royalty recipient
An entity registered to receive a percentage of secondary sales. May be the seller or a third party.

## S

### Seller
The protocol entity that publishes offers. Created on-chain via `createSeller()`. Has an assistant key (operational signer) and an admin key (privileged signer).

### Sequential commit
The protocol allows the same offer to be committed to by multiple buyers in sequence; each commit issues a new exchange. The protocol adds explicit batch / expiration semantics on top.

### Subgraph
A Boson-maintained [Graph Protocol](https://thegraph.com) deployment that indexes on-chain events and exposes a GraphQL API for reading offers, exchanges, disputes, etc. The SDK's `Search`, `Marketplace`, and per-domain `subgraph` modules hit this. Lags 1–3 blocks behind chain. See [Eventing & indexing](/concepts/eventing).

## T

### Token-gated offer
An offer with a `condition` that restricts who may commit (e.g. "must hold ≥ 1 of NFT X"). Configured at offer creation.

## V

### Voucher
See **rNFT**.

## W

### Web3LibAdapter
The pluggable interface that abstracts the Ethereum library (ethers v5 today; viem bridged via `walletClientToWeb3LibAdapter()`). `CoreSDK` is instantiated with one. See [Reference → Core SDK → Adapters](/reference/core-sdk/adapters).

## X

### x402
[x402.org](https://x402.org) is an open standard for in-band HTTP-402 payments. Boson's `x402b` repo extends it with on-chain escrow, fulfillment channels, and a facilitator service. See [Build with x402](/x402).

---

# Pick your integration

URL: https://www.bosonprotocol.io/docs/pick-your-integration

> A decision tree for choosing between the SDK, MCP, widgets, x402, the dApp, and WooCommerce.

# Pick your integration

Boson exposes six interaction surfaces. Pick one — they all talk to the same on-chain protocol.

| If you want to… | Use | 
| --- | --- | 
| Accept payment over HTTP with escrow | [x402 escrow stack](/tooling/x402) | 
| Build an autonomous buyer/seller agent | [MCP stack](/tooling/mcp) | 
| Add a buy button to an existing site | [Commit Widget](/tooling/widgets) | 
| Sell from a WordPress / WooCommerce store | [WooCommerce plugin](/tooling/woocommerce) | 
| Sell without writing code | [The Boson dApp](/tooling/dapp) | 
| Build a marketplace, drop, or storefront | [Core SDK](/tooling/core-sdk) (+ [React Kit](/tooling/react-kit)) | 
| Integrate at the contract level | [Solidity / contracts](/tooling/contracts) | 

## Decision tree

```mermaid
flowchart TD
    Start{Are you<br/>writing code?}
    Start -- No --> dApp[The Boson dApp<br/><i>web UI, no code</i>]
    Start -- No --> Woo[WooCommerce plugin<br/><i>if you run WordPress</i>]
    Start -- Yes --> Audience{Building for<br/>humans or agents?}

    Audience -- Humans --> NeedUI{What do<br/>you need?}
    NeedUI -- Drop-in UI --> Widgets[Embeddable widgets]
    NeedUI -- Full marketplace --> SDK[Core SDK<br/>+ React Kit]
    NeedUI -- Just the contract --> Sol[Solidity / contracts]

    Audience -- AI agents --> AgentTool{What rails?}
    AgentTool -- Typed MCP toolkit --> MCP[MCP stack<br/><i>GOAT plugin or BosonMCPClient</i>]
    AgentTool -- HTTP-402 payments --> X402[x402 escrow stack]
```

## Stack capabilities at a glance

See [Tooling overview → Stack comparison](/tooling) for a full feature × maturity table.

## What's the same regardless of stack

These five things apply to every integration. Bookmark them:

- [Networks & ConfigIds](/concepts/networks-and-configids) — which chain you're talking to.
- [Signing & meta-transactions](/concepts/signing) — how to sign, who pays gas.
- [Exchange state machine](/concepts/exchange-state-machine) — what states a commitment can be in and who can move it.
- [Eventing & indexing](/concepts/eventing) — how to watch for state changes (and why the subgraph lags).
- [Going to production](/concepts/production) — the security and operational checklist.