Allowlist a wallet

Some offers only settle to wallets that the issuer has allowlisted. Superstate assets work this way, and the same allowlists are what make permissioned Uniswap pools and RWA lending markets available to your users. authorizeWallet does both halves of that in one call: it proves the user controls the wallet by having them sign a challenge, then registers the address against the offer, broadcasting an allowlist transaction if the contract requires one.

The flow involves two identities. The CoinList session (from OAuth) identifies who is investing, and the wallet is where assets are delivered. Allowlisting is what links them, which is why the user signs a message before they can transact.

Prerequisites

A completed OAuth session with a working CoinListProvider
A connected wallet. Wallet selection and connection are your app’s responsibility - the SDK operates on an already-connected EvmWallet.

Authorize a wallet

const result = await coinlist.swap.authorizeWallet({
  wallet,
  offerId: OFFER_ID,
  contractAddress: SWAP_CONTRACT_ADDRESS,
  chain: SWAP_CHAIN,
  onProgress: (phase) => setPhase(phase),
});

if (result.type === "success") {
  setAuthorized(true);
} else {
  setError(result.error.step);
}

authorizeWallet is idempotent. If the wallet is already authorized it returns success immediately without prompting the user, so it is safe to call at the start of every session. Flow-level failures come back as { type: "error" } rather than throwing.

Parameters

Parameter	Type	Description
`wallet`	`EvmWallet`	An already-connected wallet that can sign messages and send transactions.
`offerId`	`OfferId`	The offer to allowlist the wallet against.
`contractAddress`	`EvmContractAddress`	The swap contract for the offer.
`chain`	`EthereumChain`	The EVM chain to authorize on, for example `ethereum_mainnet`.
`onProgress`	`(phase: WalletAuthorizationPhase) => void`	Optional. Called as the flow advances, for rendering loading states.

Progress phases

The phases are emitted in order. Two of them open a wallet popup: checking-authorization → requesting-challenge → signing-message (wallet popup) → submitting-signature → broadcasting-transaction (wallet popup, only when the contract needs an allowlist transaction) → awaiting-confirmation → verifying-authorization

Error steps

WalletAuthorizationError is tagged by the step that failed, so you can tell a user rejection apart from an infrastructure problem.

`step`	What happened
`authorization-check`	The initial check for existing authorization failed.
`challenge-request`	Requesting the ownership challenge failed.
`signing`	The user did not sign the challenge. Carries a `cause` of type `WalletError`.
`allow-wallet`	Submitting the signature to allowlist the wallet failed.
`broadcast`	Broadcasting the allowlist transaction failed. Carries a `cause` of type `WalletError`.
`not-authorized`	The flow completed but the on-chain re-check still reports the wallet as unauthorized.

The signing and broadcast steps carry a WalletError cause, which distinguishes user_rejected from insufficient_funds, contract_reverted, and timeout. See Errors and edge cases for the full breakdown and for guidance on which are worth retrying.

Underlying endpoints

authorizeWallet wraps three Frontline API endpoints. Use them directly only if you are not using the React SDK.

Endpoint	Purpose
`GET /v1/wallet/authorized`	Reads `authorized(address)` on the swap contract to check whether a wallet may transact.
`POST /v1/wallet-ownership`	Requests a challenge for the user to sign.
`POST /v1/offers/{offer_id}/allow-wallet`	Submits the signature and allowlists the address for the offer.

Get started

Offers and participations

Flows

Reference

Prerequisites

Authorize a wallet

Parameters

Progress phases

Error steps

Underlying endpoints

Next steps

Swap flow

Errors and edge cases

​Prerequisites

​Authorize a wallet

​Parameters

​Progress phases

​Error steps

​Underlying endpoints

​Next steps

Swap flow

Errors and edge cases

Prerequisites

Authorize a wallet

Parameters

Progress phases

Error steps

Underlying endpoints

Next steps