Listing auth (SIWE)

Everything a user owns on the listing backend — their pools, their stake, their revenue, and the create/withdraw/claim actions — is gated by a Bearer token, not by a wallet filter. This page mints that token. It is a Sign-In With Ethereum (EIP-4361) exchange: fetch a challenge, sign it with the wallet, hand the signature back, and receive the token.

The flow is three steps, and authenticateListing runs all three for you:

1. GET /v2/auth/sign-in-message → an EIP-4361 message string plus its structured params.
2. sign the message string with the wallet (personal_sign).
3. POST /v2/auth/login with the params + signature → { accessToken, tokenType }.

There is no separate nonce round-trip — the sign-in message already embeds a single-use nonce.

Every function here resolves the listing backend through resolveListingService, so listing is chain-level: a chain without a listing backend throws LISTING_NOT_CONFIGURED before any network call.

authenticateListing

The whole flow in one call. Resolves the wallet client from the config, signs with its account, and returns the token.

import { authenticateListing } from "@symmio/trading-core";
 
const { accessToken, tokenType } = await authenticateListing(config, {
  domain: "app.example.com", // the SIWE DNS authority — no scheme
  uri: "https://app.example.com", // the requesting dApp URI
});
// accessToken is the "access code": send it as `Authorization: Bearer <accessToken>`.

The signing address is the wallet account’s own address — it is read from config.getWalletClient(), not passed in. Point from at a specific signer when the config resolves more than one (e.g. a session key vs. the connected wallet).

Parameters

Exported as AuthenticateListingParameters.

Returns

Throws

• LISTING_NOT_CONFIGURED — a SymmError (kind: "config") from resolveListingService, before any request, when the chain has no listing backend configured.
• LISTING_LOGIN_FAILED — a SymmApiError when /v2/auth/login rejects the signature or errors.
• The wallet’s own rejection (viem UserRejectedRequestError) passes through unwrapped when the user declines the signature.

As a mutation

For TanStack, authenticateListingMutationOptions wraps it:

import { authenticateListingMutationOptions } from "@symmio/trading-core";
import { useMutation } from "@tanstack/react-query";
 
const login = useMutation(authenticateListingMutationOptions(config));
login.mutate({ domain: "app.example.com", uri: "https://app.example.com" });

In React, reach for useAuthenticateListing instead — it fills domain / uri from the current origin.

getListingSignInMessage

Step 1 on its own, for callers that sign the message themselves (a custom signer, a hardware flow, a server relay). Returns the challenge; you sign message and post it to login yourself.

import { getListingSignInMessage } from "@symmio/trading-core";
 
const { message, params } = await getListingSignInMessage(config, {
  address: "0xUser…",
  domain: "app.example.com",
  uri: "https://app.example.com",
});

Parameters

Exported as GetListingSignInMessageParameters.

Returns

Related

• useAuthenticateListing — the React hook, with domain / uri defaulted to the current origin.
• resolveListingService — the availability gate every auth call runs first.
• Pools — the slice overview.
• Errors — the SymmError / SymmApiError hierarchy these codes belong to.