Wallet status

Check if a wallet belongs to a verified Signa ID, from your page or your server.

The wallet status tells you if a wallet address belongs to a person with a verified Signa ID. The answer holds no personal data. It holds only the facts that the on-chain attestation already makes public.

Use it to let a verified wallet continue, for example on a smart-contract exchange. You need no Blaaiz account, no credentials, and no backend.

Read the status

Send a GET request with the wallet address and the chain id:

curl -X GET "https://api-prod.blaaiz.com/api/v1/signa-id/public/wallets/0x3efb62350e7176f070ed9e09b033b646f9a0564c/status?chain_id=8453"
{
  "verified": true,
  "level": 1,
  "country": "NGA",
  "expires_at": "2027-09-12T14:03:51.000Z",
  "attestations": [
    {
      "chain_id": 8453,
      "uid": "0xbe0fddf230a69817f77d6938be311e83c864b052f1b2f4b7b420345babbd6dc7",
      "explorer_url": null
    }
  ]
}

The response is the status object, with no message and no data wrapper.

FieldDescription
verifiedtrue when the wallet belongs to a verified Signa ID.
level1: the person verified an identity document. 2: the person also verified a proof of address. null when verified is false.
countryThe country of the verification, as an ISO 3166-1 alpha-3 code. null when verified is false.
expires_atWhen the verification expires. null when verified is false.
attestationsThe on-chain attestations for the wallet. Each item has chain_id, uid and explorer_url. explorer_url is null for a chain with no explorer.
ParameterDescription
addressThe wallet address: 0x and 40 hexadecimal characters.
chain_idOptional. The chain id, from 1 to 4294967295.

A wallet that Blaaiz does not know, a wallet with no verification, and an expired verification all get the same answer, with status 200:

{
  "verified": false,
  "level": null,
  "country": null,
  "expires_at": null,
  "attestations": []
}

An address or a chain_id in the wrong format returns 422.

Use the web SDK

The Signa web SDK reads the status for you, and can ask the person to verify.

  1. Call signa.status() when the page loads. This call shows nothing to the person.
  2. Call signa.verify() when the person selects a button.
import { createSigna } from '@blaaiz/signa-web-sdk';

const signa = createSigna({ environment: 'production' });

await signa.status({ wallet, chainId: 8453 }); // on page load

button.onclick = async () => {
  const status = await signa.verify({ wallet, chainId: 8453 });
  if (status.verified) {
    // Let the person continue.
  }
};

verify() returns at once for a verified wallet. For a wallet that is not verified, it shows the Signa ID connect page. From version 3.0.0 of the web SDK, the page shows in a dialog on your page by default. On the page, the person signs in with an email code, verifies if necessary, and links the wallet. The person signs in each time. The SDK then reads the status again and returns it.

  • If the person closes the dialog or the popup, verify() returns the current status. That status is not verified.
  • If a dialog or a popup for a different wallet is open, verify() rejects with code: 'in_progress'.
  • An address that is not 0x and 40 hexadecimal characters rejects at once.

Some wallet extensions do not run inside the frame of another site. If the wallet of the person does not show in the dialog, pass mode: 'popup':

const status = await signa.verify({ wallet, chainId: 8453, mode: 'popup' });

In popup mode:

  • Call verify() from the click handler of a button. If the browser blocks the popup, verify() rejects with code: 'blocked'.
  • Some browsers allow only a short time between the click and the popup. Call status() before the click. When status() ran in the last 60 seconds and the wallet is not verified, verify() opens the popup at once.
  • Do not send the Cross-Origin-Opener-Policy: same-origin header on the page. Use same-origin-allow-popups, or send no header.

In embedded mode, the page must allow the Signa ID site in a frame and allow the camera for it. See Page requirements.

Caching and limits

  • The endpoint needs no authentication and accepts calls from any origin.
  • A 200 response carries Cache-Control: public, max-age=60. A change can take up to one minute to show. The SDK also keeps each status() result for 60 seconds.
  • The endpoint allows 60 requests each minute and 1,000 requests each hour for each IP address. Above the limit, the call returns 429.

On this page