Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Core SDK · Boson Protocol
Skip to content

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

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

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.

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.

MixinReferenceWhat it covers
Accounts→createSeller, createBuyer, createDisputeResolver, role management
Offers→createOffer, voidOffer, querying offers
Exchanges→commitToOffer, redeemVoucher, completeExchange, cancelVoucher
Disputes→raiseDispute, resolveDispute, escalateDispute, decideDispute
Funds→depositFunds, withdrawFunds, getting balances
MetaTx→EIP-712 signing helpers, Biconomy relay support
Orchestration→Atomic combos like createOfferAndCommit, createOfferCommitAndRedeem
Groups→Token-gating conditions
Marketplace→Subgraph-backed marketplace queries
Search→Full-text and faceted search over offers
ERC20 / 721 / 1155→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.
  • You want a drop-in commit button → Embeddable widgets (no SDK needed).
  • You're building an autonomous agent → MCP stack. You can use the SDK from an agent, but MCP gives you a typed tool registry for free.

Versioning

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