Open SuperRare commerce in a hosted window.

SuperRare Connect is a browser SDK for hosted buy, sell, bid, mint, settle, offer, transfer, checkout, authentication, and intent-status flows. Studio remains the host; Connect remains responsible for commerce and wallet execution.

Connect is the fee authority

Connect displays and applies its current fee structure inside its hosted commerce flows. Studio does not calculate, add, or override Connect fees.

Install and create a client

npm install --save-exact @rareprotocol/connect@0.11.0

import { createSuperRareClient } from "@rareprotocol/connect";

const superrare = createSuperRareClient({
  onIntentSettled: (intent) => refreshOrder(intent),
});

The package ships ESM, CommonJS, and a browser-global (SuperRareConnect) build. Options include apiUrl and connectUrl for test environments, popup sizing, onIntentSettled, a custom fetch, and sessionStorage: false for apps that do not want SDK-managed browser storage.

Hosted windows

Every flow opens in a small centered window, so your page keeps its state while the user signs in or pays. Call the action directly from a click handler: the window opens synchronously inside the user gesture. If the browser blocks it, the call rejects with ConnectPopupBlockedError before any intent is created. onIntentSettled reports the final status when the flow finishes, or the latest known state if the user closes the window early, so check intent.status before acting on it.

Commerce actions

await superrare.actions.buy({
  target: {
    kind: "erc721-direct-listing",
    chainId: 1,
    contract: "0x…",
    tokenId: "1",
  },
  expected: { currency: "ETH", price: "1000000000000000" }, // wei
  returnPath: "/connect/return",
});

actions.buy

Buy an ERC-721 direct or batch listing, an ERC-1155 listing, or a Liquid Edition.

actions.sell

Sell a Liquid Edition for ETH, RARE, or USDC.

actions.bid

Bid on a reserve, batch reserve, or scheduled auction.

actions.mint

Mint from an ERC-721 or ERC-1155 release.

actions.settle

Settle an ended reserve auction.

actions.transfer

Send an exact ETH or USDC amount to a wallet you name.

offers.make / accept / cancel

Make, accept, or cancel ERC-721 offers, including batch offers.

checkout.start

Start an ERC-1155 checkout.

Prices and amounts are raw base-unit strings: wei for ETH and 6 decimals for USDC. Every action except transfer accepts payment: { method: "wallet" } to keep the checkout wallet-only. Use it when a custom contract keys anything on the receiving wallet, because card settlement delivers through a SuperRare buy proxy.

Transfers for off-chain goods

await superrare.actions.transfer({
  chainId: 1,
  to: "0x…", // your wallet
  currency: "USDC",
  amount: "25000000", // 25 USDC
  beforeOpen: async ({ intentId }) => {
    await linkOrder("order_123", intentId);
  },
});

Transfers are wallet-only. beforeOpen runs after the intent is created and before the window shows the payment; if it throws, the window closes and the call rejects, so the user never sees a payment your backend has not recorded.

Credit only from your backend

Nothing the page reports proves a payment. Your backend reads GET /v1/connect/intents/:intentId itself and credits each intent once, only when status is completed, actionType is transfer, and the terms chainId, recipient, amount, and currency match the order.

Intent status

import { resolveConnectIntentOutcome } from "@rareprotocol/connect";

const intent = await superrare.intents.get({ intentId });
const outcome = resolveConnectIntentOutcome(intent);

switch (outcome.kind) {
  case "pending":   showPending(); break;
  case "completed": showSuccess(); break;
  case "failed":    showFailure(outcome); break;
}

returnPath must be relative

Use a same-origin path such as /connect/return. Absolute URLs, protocol-relative paths, backslashes, control characters, and encoded bypasses are rejected. Never substitute a returnUrl.

Authentication and user data

auth.login

auth.prepareLogin

Create the login ahead of the tap so iOS Safari opens the window already loaded.

auth.getSession / getRemoteSession

Read the cached local session or the server-backed session state.

auth.getAccessToken

Get a current access token right before calling your backend; sessions refresh automatically.

auth.onChange / logout

Observe session changes or end the Connect session.

user.me

Read the current Connect user after authentication.

Connect authentication is optional for checkout, buy, bid, mint, settle, transfer, and status flows. It does not replace Studio login.

Test on Sepolia

const superrare = createSuperRareClient({
  apiUrl: "https://rare-api-dev-mainnet.superrare.co",
  connectUrl: "https://connect-dev-mainnet.superrare.co",
});

Production executes Ethereum mainnet only. The dev pair above executes both mainnet and Sepolia: pass chainId: 11155111 on the action target and use a wallet funded with Sepolia ETH. Switch back to the defaults for production.

Errors and production readiness

Handle ConnectPopupBlockedError, ConnectActionValidationError, ConnectReturnPathError, ConnectSessionRequiredError, and SuperRareConnectApiError as distinct states. The SDK intentionally rejects arbitrary calldata, contract instructions, private keys, API secrets, and wallet-provider objects.

Exercise the configured test environment
Render pending, completed, failed, and interrupted
Verify identifiers and chain
Keep Studio and Connect sessions separate
Recover from a closed hosted window
Do not infer success from the window closing
Confirm card settlement before fulfillment
Credit transfers only from your backend

Open the public repository npm package