Start Here

What you can do with Holonym and How

While Holonym can be used off-chain it is by far most commonly used on-chain. We use the term Soul-Bound Token (SBT) to refer to an on-chain record linked to a user's address. To use Holonym, you simply must direct the user to get their SBT, then you can read the SBT from from our API in one line of code, or from the blockchain itself.

1. Send a user to Holonym to get an SBT

You may send the user to<silkOrDiffWallet>/<credentialType>/issuance/prereqs

for our new & improved UI. silkOrDiffWallet is either silk (if you want the user to use Holonym within their Silk account) or diff-wallet (if you want to let the user use Holonym with a wallet other than Silk). credentialType is either gov-id (for government ID credentials) or phone (for phone number credentials). The gov-id credentials are verified with a KYC flow.

Alternatively for the old UI you may direct them to:<credentialType>

WherecredentialType is either idgov (for government ID credentials) or phone (for phone number credentials).


Users can also verify using an NFC-enabled government ID document. Please see How to Verify ePassport for user instructions.

Note that the ePassport SBT is distinct from the gov-id SBT. A user can get both an ePassport SBT and a gov-id (KYC) SBT.

Option B (Coming Soon): Via Silk SDK

To directly embed Holonym / Silk into your website, you will be able to instead import the Silk SDK and call


WherecredentialType is either 'idgov' (for government ID credentials) or 'phone' (for phone number credentials).

2. Read a user's SBT

Option A: Holonym API

To check whether a user has a certain SBT, you can query the Holonym API. The JavaScript example shows how to call the Holonym API (which calls the SBT smart contract) to get whether the user is unique for the given action ID.

// `action-id` is the action ID. The only action ID currently 
// in use is 123456789.
// `user` is the address to be checked.
const resp = await fetch('');
const { result: isUnique } = await resp.json();

Option B (DEPRECATED): On chain

You can call the SBT contract directly. The Solidity example gives anyone 1 gwei who has proven they're from the US. (See more examples in the examples repo.)

// NOTE: This example is deprecated with Holonym V3.

pragma solidity ^0.8.0;
import "../interfaces/IResidencyStore.sol";

// US Residents have had it hard this year! let's send 1 gwei to anyone who can prove they're from the US
contract USResidency {
    IResidencyStore resStore;
    constructor() {
        resStore = IResidencyStore(0x7497636F5E657e1E7Ea2e851cDc8649487dF3aab); //ResidencyStore address can be found on

    // NOTE: there are better ways to send ETH. Please don't copy this code
    function sendStimmy() public {
        require(resStore.usResidency(msg.sender), "You have not proven you are from the US");

You may have noticed one person can claim the gwei many times in the Solidity example! This an example; please do not implement a US stimulus program from it.

Note: by default, proofs can only be done once-per-ID to prevent Sybil attacks & bribery. You don't want somebody to sell their US residency proof to others. This means a user can only verify one of their addresses as being a US resident.

Example: Sybil Resistance

1. Send users to Holonym to get government ID uniqueness SBTs

Send users to the following URL.

Users will complete verification and get an SBT at the address of their choosing.

2. Read users' uniqueness SBTs

The below JS example checks whether an address belongs to a unique person.

The smart contract in Solidity gives a privacy-preserving airdrop once-per-person to only unique people.

//`user` is the address that should be checked for uniqueness
// `action-id` should be 123456789, unless you specified a custom action ID
const resp = await fetch('');
const { result: isUnique } = await resp.json();

Note: we highly recommend using the default actionID of 123456789. If you would like to explore custom actionIDs, please see Custom Sybil Resistance. Otherwise, feel free to ignore the concept of an actionID and just use 123456789as shown in the example.

Last updated