Wallets: the EvmWallet seam

The SDK ships no wallet stack. It is not coupled to Privy, Turnkey, AppKit, wagmi, or anything else, and it never asks a user to connect. Wallet discovery, connection, and disconnection are your app’s job. That is deliberate. A partner may be a wallet provider themselves, and every partner already has a wallet story before they reach Passage. So the SDK inverts it: you implement one small interface, EvmWallet, and the SDK drives it. Do that once and every on-chain flow works - Superstate swaps, Ondo buys, token-sale approvals, ownership proofs.

The SDK uses and ships viem types, the de-facto TypeScript standard for Ethereum, so the interface lines up with whatever you are already using. A SolanaWallet seam will follow the same shape when Solana lands.

Two shapes, one seam

There are two interfaces, and the smaller one is a subset of the larger.

Interface	Members	Needed for
`EvmSigner`	`address`, `signMessage`	Proving wallet ownership. No gas, no transaction.
`EvmWallet`	the two above, plus `writeContract`, `broadcastRawTx`, `awaitTx`	Everything on-chain: approvals, swaps, allowlist transactions.

EvmWallet extends EvmSigner, so implementing the full interface satisfies both. If all you need is the requirements checklist binding a wallet to an offer option, EvmSigner is enough and your users never see a gas prompt.

Implement EvmWallet

import type { EvmWallet } from "@coinlist-co/react";

Member	Signature	What the SDK does with it
`address`	`EvmWalletAddress`	Reads balances and allowances, and names the sender.
`signMessage`	`(message: string) => Promise<Hex>`	Ownership challenges and allowlist authorization.
`writeContract`	`(params: WriteContractParams) => Promise<Hash>`	ERC-20 `approve`, and any contract call the SDK encodes itself.
`broadcastRawTx`	`(params: BroadcastTxParams) => Promise<Hash>`	Sends backend-encoded calldata verbatim. Never re-encode it: the contract verifies a signature over the exact arguments inside.
`awaitTx`	`(hash: Hash, chain: EthereumChain) => Promise<TransactionReceipt>`	Waits for confirmation before advancing a flow.

Every method that takes a chain gets it as an explicit parameter. Switch the wallet to that chain before acting - the SDK does not assume your wallet is already pointed at the right one.

Adapter: wagmi and AppKit

This is the canonical adapter, and it is the one the partner demo runs. Any stack that can sign a message and send a transaction works the same way.

wagmiEvmWallet.ts

import type { EvmWallet } from "@coinlist-co/react";
import type {
  EthereumChain,
  EvmWalletAddress,
} from "@coinlist-co/react/shared";
import {
  type Config,
  getChainId,
  switchChain,
  waitForTransactionReceipt,
} from "@wagmi/core";
import { type Chain, encodeFunctionData, type WalletClient } from "viem";
import { mainnet, sepolia } from "viem/chains";

const CHAINS: Record<EthereumChain, Chain> = {
  ethereum_mainnet: mainnet,
  ethereum_sepolia: sepolia,
};

export function buildEvmWallet({
  address,
  walletClient,
  config,
}: {
  address: EvmWalletAddress;
  walletClient: WalletClient;
  config: Config;
}): EvmWallet {
  const account = address as `0x${string}`;

  // Each call passes the target chain; switch the wallet there first.
  const ensureChain = async (chain: EthereumChain): Promise<Chain> => {
    const target = CHAINS[chain];
    if (getChainId(config) !== target.id) {
      await switchChain(config, { chainId: target.id });
    }
    return target;
  };

  return {
    address,
    signMessage: (message) => walletClient.signMessage({ account, message }),
    async writeContract({ abi, address: to, functionName, args, value, chain }) {
      const targetChain = await ensureChain(chain);
      const data = encodeFunctionData({ abi, functionName, args });
      return walletClient.sendTransaction({
        account,
        chain: targetChain,
        to,
        data,
        value,
      });
    },
    async broadcastRawTx({ to, data, chain }) {
      const targetChain = await ensureChain(chain);
      return walletClient.sendTransaction({ account, chain: targetChain, to, data });
    },
    awaitTx: (hash, chain) =>
      waitForTransactionReceipt(config, { hash, chainId: CHAINS[chain].id }),
  };
}

npm install @coinlist-co/react wagmi @wagmi/core viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query

Let wallet errors propagate

Do not catch and translate your wallet library’s errors. Let them throw. The SDK catches them and classifies them into a typed WalletError, so you never parse a wallet error string yourself:

`WalletError`	Cause
`user_rejected`	The user dismissed the wallet prompt.
`insufficient_funds`	Not enough native token for gas, or not enough balance.
`contract_reverted`	The transaction was mined and reverted.
`timeout`	Confirmation did not arrive in time.
`unknown`	Anything the SDK could not classify.

Flows surface it as the cause on the step that failed, so you can tell a user rejection apart from an infrastructure problem. See Errors and edge cases for the full breakdown.

Proving wallet ownership

Two identities are involved in every Passage purchase, and they are not the same thing:

The CoinList session (from OAuth) identifies who is investing.
The wallet is where the assets are delivered.

An ownership proof is what links them, which is why the user signs a message before they can transact. Some offers go further: the issuer only settles to wallets they have allowlisted. Superstate assets work this way, and the same allowlists are what make permissioned DeFi pools and RWA lending markets reachable. Ownership proof is provider-agnostic, so it lives on the platform namespace rather than being duplicated per provider:

const challenge = await coinlist.wallets.createOwnershipChallenge({
  challengeType: "siwe",          // or "plain"
  walletAddress: wallet.address,
  chain: "ethereum_mainnet",
  domain: window.location.host,
  uri: window.location.origin,
  statement: "Sign to prove you own this wallet.",
});

const signature = await wallet.signMessage(challenge.message);

const binding = await coinlist.wallets.connectExternal({
  offerId,
  offerOptionId,
  walletAddress: wallet.address,
  chain: "ethereum_mainnet",
  signature,
});

coinlist.wallets also reads and removes those bindings: list({ offerId, offerOptionId }) returns the wallets bound to an option, and remove({ offerId, addressId }) unbinds one.

You rarely need to write the sequence above. RequirementsChecklistContainer runs it for you when an offer has an external_wallet or whitelisted_wallet requirement, and the Superstate Swap allowlist flow wraps it in one idempotent call.

CheckoutWalletSelection: what checkout takes

EvmWallet is what the SDK drives. CheckoutWalletSelection is what you hand CheckoutContainer: the wallets the buyer may spend from, plus the two lambdas that connect and disconnect an external one.

import type { CheckoutWalletSelection } from "@coinlist-co/react";

const wallets: CheckoutWalletSelection = {
  // The user's embedded (custodial) wallets, in display order.
  // Empty is a normal state, not an error.
  embedded: embeddedWallets,
  // The connected external wallet, or null while none is connected.
  external: externalWallet,
  // Opens your wallet connector. The SDK reads the outcome from `external`
  // on the next render, not from a return value, so a redirect-based
  // connector works. Reject to report a declined or failed connection.
  connectExternal: () => openConnectModal(),
  disconnectExternal: () => disconnect(),
};

There is deliberately no separate wallet model here: EvmWallet already carries the address, so an { address, signer } pair would be a second wallet type to keep in sync with the first. Everything a wallet row displays beyond the address - the network name - comes from the checkout’s execution chain rather than from the wallet, because that is the chain the transaction goes to whatever the wallet is currently pointed at.

Next step

Building the Checkout flow

Hand your wallets to CheckoutContainer and let it render whichever provider the offer belongs to.

Get started

Offers and requirements

Flows

Reference

Wallets: the EvmWallet seam

Two shapes, one seam

Implement EvmWallet

Adapter: wagmi and AppKit

Let wallet errors propagate

Proving wallet ownership

CheckoutWalletSelection: what checkout takes

Next step

Building the Checkout flow

​Two shapes, one seam

​Implement EvmWallet

​Adapter: wagmi and AppKit

​Let wallet errors propagate

​Proving wallet ownership

​CheckoutWalletSelection: what checkout takes

​Next step

Building the Checkout flow

Two shapes, one seam

Implement EvmWallet

Adapter: wagmi and AppKit

Let wallet errors propagate

Proving wallet ownership

CheckoutWalletSelection: what checkout takes

Next step