API Reference

This page documents the public types, props, and hooks exported by @averer/averer-websdk.

AvererSdkProvider

The provider component that wraps your application and initialises the SDK.

<AvererSdkProvider configId="your-config-id">{children}</AvererSdkProvider>

Prop	Type	Required	Description
`configId`	`string`	Yes	Your Averer configuration ID. Contact Averer support to obtain one.
`loadingFallback`	`ReactNode`	No	UI rendered while the initial config fetch is in flight. Defaults to `null` (no visible UI), matching pre-existing behaviour.
`errorFallback`	`ReactNode \\| ((error: SdkConfigError, retry: () => void) => ReactNode)`	No	UI rendered if the config fetch fails. Defaults to a built-in red error message. Use the function form to receive the classified error and a `retry` callback (see example).
`onError`	`(error: SdkConfigError) => void`	No	Side-channel for telemetry. Fires on every error transition (initial failure and each failed retry); not called on success.
`disableInternalBoundary`	`boolean`	No	If `true`, the SDK will not provide its own `<Suspense>` and error boundary. You are then responsible for wrapping `<AvererSdkProvider>` with your own `<Suspense>` and error boundary so the SDK's loading and error states can be caught.

Example — custom error UI with a retry button:

<AvererSdkProvider
  configId="your-config-id"
  loadingFallback={<Spinner />}
  errorFallback={(error, retry) => (
    <div>
      <p>Failed to initialise the SDK ({error.code}): {error.message}</p>
      <button onClick={retry}>Try again</button>
    </div>
  )}
  onError={(error) => Sentry.captureException(error)}
>
  <App />
</AvererSdkProvider>

SdkConfigError

Thrown by the SDK when the initial configuration fetch fails. Surfaced to hosts via the errorFallback and onError props on AvererSdkProvider.

class SdkConfigError extends Error {
  readonly code: SdkConfigErrorCode;
  readonly cause?: unknown;
}

type SdkConfigErrorCode =
  | 'network'
  | 'invalid_config_id'
  | 'decode_failed'
  | 'unsupported_chain'
  | 'unknown';

`code`	When it fires
`network`	The fetch could not complete (DNS, CORS, connectivity) or the config server returned a 5xx response.
`invalid_config_id`	`configId` was empty/missing, or the config server returned a 4xx response.
`decode_failed`	The response could not be parsed as JSON, or the JWT signature/payload could not be verified.
`unsupported_chain`	The decoded config references a chain ID that this SDK version does not support.
`unknown`	Anything else. Treat as terminal and surface a generic error to the user.

Use error.code to branch UX (e.g. show "Try again" only for network); the standard error.cause field carries the underlying error.

AvererWebSdk

The main SDK component that renders the verification flow UI.

type AvererWebSdkProps = {
  appName: string;
  mode?: 'individual' | 'business';
  settings?: {
    testing?: {
      socialLinkingRequired?: boolean;
    };
  };
  sdkQuery: SdkQuery;
  onChainMetaData?: {
    contract_address: string;
    method_id: string;
  };
  onSuccess?: (data: SdkSuccessRes) => void;
  onError?: (reason: string) => void;
};

Prop	Type	Required	Description
`appName`	`string`	Yes	Name of your application, displayed in the SDK UI.
`mode`	`'individual' \\| 'business'`	No	Verification flow mode. Defaults to `'individual'`. Use `'business'` for KYB.
`settings`	`object`	No	Optional SDK settings. `settings.testing.socialLinkingRequired` is a testing-only override for the social-linking gate and is ignored in production Dynamic environments.
`sdkQuery`	`SdkQuery`	Yes	Eligibility criteria the user must satisfy.
`onChainMetaData`	`object`	No	If provided, SDK submits proofs on-chain. `method_id` should be `'b68967e2'` (submitZKPResponse V1) or `'ade09fcd'` (submitZKPResponseV2).
`onSuccess`	`function`	No	Callback fired when all queries are successfully proven.
`onError`	`function`	No	Callback fired when the user cancels, rejects, or an error occurs.

In non-production Dynamic environments, social linking is disabled by default. You can re-enable it during QA by passing:

<AvererWebSdk
  appName="My App"
  sdkQuery={sdkQuery}
  settings={{
    testing: {
      socialLinkingRequired: true,
    },
  }}
/>

useAvererWallet

A React hook that provides access to the user's embedded wallet. Must be used within an AvererSdkProvider.

import { useAvererWallet } from '@averer/averer-websdk';

const wallet = useAvererWallet();

Returns an object with:

Property / Method	Type	Description
`address`	`string`	The user's blockchain wallet address.
`onChainIdentityAddress`	`string \\| undefined`	Optional ONCHAINID contract address created after KYC/KYB. Resolved from Dynamic metadata using the connected wallet address as the lookup key.
`getPublicClient()`	`() => Promise<PublicClient>`	Returns a Viem Public Client for read-only blockchain operations.
`getWalletClient()`	`() => Promise<WalletClient>`	Returns a Viem Wallet Client for signing and sending transactions.
`getBalance()`	`() => Promise<string \\| undefined>`	Returns the wallet's token balance when available.
`signMessage(message)`	`(message: string) => Promise<string \\| undefined>`	Signs an arbitrary message with the wallet's private key.
`ensureMfaForSigning()`	`() => Promise<void>`	Checks if MFA is required before signing or sending a transaction. Call before `signMessage` or `sendTransaction`.
`getEOAWallet()`	`() => Wallet \\| undefined`	Returns the underlying EOA wallet for the connected smart wallet, when available.
`logout()`	`() => void`	Signs the user out and resets the SDK to the eligibility screen. After logout, `useAvererWallet()` returns `null`.

Returns null if the wallet is not yet connected.

SdkQuery

The type for defining eligibility criteria.

type SdkQuery = Array<{
  id: number;
  circuitId: string;
  subjectTitle: string;
  optional?: boolean;
  query: ZeroKnowledgeProofQuery;
  params?: {
    nullifierSessionId?: string | number;
  };
}>;

Field	Type	Description
`id`	`number`	A unique numeric identifier for the query. For on-chain queries, this must match the `requestId` on the verifier contract.
`circuitId`	`string`	Circuit used for proof generation. Use `credentialAtomicQuerySigV2` for off-chain or `credentialAtomicQuerySigV2OnChain` for on-chain.
`subjectTitle`	`string`	Short title describing the verification purpose (e.g. "18+ Years Old").
`optional`	`boolean`	If `true`, this query is not required for the overall eligibility check to pass.
`query`	`ZeroKnowledgeProofQuery`	The proof requirements and constraints.
`params`	`object`	Optional parameters. `nullifierSessionId` can be used for nullifier-based proofs.

ZeroKnowledgeProofQuery

The type for defining proof requirements within a query.

type ZeroKnowledgeProofQuery = {
  allowedIssuers: string[];
  context: string;
  credentialSubject?: JsonDocumentObject;
  proofType?: string;
  skipClaimRevocationCheck?: boolean;
  groupId?: number;
  type: string;
};

Field	Type	Description
`allowedIssuers`	`string[]`	List of issuer DIDs permitted to provide the credential. `['*']` allows any issuer; use trusted issuer DIDs in production and mainnet flows.
`context`	`string`	JSON-LD context URL defining the credential schema.
`credentialSubject`	`object`	Conditions or fields to verify. Use operators like `$eq`, `$lt`, `$gt`, `$in` for conditions, or an empty object `{}` for selective disclosure.
`proofType`	`string`	Optional proof type override.
`skipClaimRevocationCheck`	`boolean`	Optional iden3/Privado flag. If `true`, skips credential revocation enforcement. Omit it for production and mainnet flows; use `true` only for clearly marked testing or non-production flows.
`groupId`	`number`	Optional group identifier for linking related queries.
`type`	`string`	The credential type (e.g. `AMLCTFCredential`, `EssentialIdCredential`).

SdkSuccessRes

The type returned in the onSuccess callback when verification completes.

type SdkSuccessRes = {
  walletAddress: string;

  user: {
    email?: string;
    isAuthenticated: boolean;
    did?: string;
  };

  proofs: Array<{
    id: string | number;
    circuitId: string;
    subjectTitle: string;
    status: 'valid' | 'failed';
    proofData: {
      credentialType: string;
      rawProof?: {
        id: number | string;
        circuitId: string;
        vp?: {
          type: string;
          verifiableCredential: {
            type: string | string[];
            credentialSubject: JsonDocumentObject;
          };
        };
      };
    };
  }>;

  eligibility: {
    passed: boolean;
    summary: string;
  };

  onChain?: {
    contract_address: string;
    method_id: string;
    chain_id: number;
    network?: string;
    txHash?: string;
  };
};

Field	Description
`walletAddress`	The user's blockchain wallet address.
`user.email`	The user's email address, if available.
`user.isAuthenticated`	Whether the user is authenticated.
`user.did`	The user's Decentralized Identifier, if available.
`proofs`	Array of proof results, one per query.
`proofs[].status`	`'valid'` if the proof was accepted, `'failed'` otherwise.
`proofs[].proofData.rawProof.vp.verifiableCredential.credentialSubject`	The actual credential data proven by the user (e.g. age, nationality).
`eligibility.passed`	`true` if the user satisfied all required proof checks.
`eligibility.summary`	Human-readable summary of the eligibility result.
`onChain`	Present only in on-chain mode.
`onChain.txHash`	The transaction hash, useful for showing "submitted / confirmed" UX.