API Reference

Reference for https://api.holonym.io

Endpoints

GET /sybil-resistance/<credential-type>/<network>?user=<user-address>&action-id=<action-id>

Get whether the user has registered for the given action-id.

When a user "registers", they are establishing that the given blockchain address is a unique person for the action ID. See the section Sybil resistance for more information about how action IDs can be used.

If credential-type is gov-id, this endpoint uses Holonym smart contracts to check whether the user has completed KYC with a unique government ID. If credential-type is epassport, this endpoint uses Holonym smart contracts to check whether the user has a unique NFC-enabled passport. If credential-type is phone, this endpoint uses Holonym smart contract to check whether the user has proven ownership of a unique phone number.

See the following documentation How to get user's proofs for how to use action IDs.

  • Parameters

    namedescriptiontypeinrequired

    credential-type

    'gov-id' or 'phone'

    string

    path

    true

    network

    'optimism' or 'optimism-goerli'

    string

    path

    true

    user

    User's blockchain address

    string

    query

    true

    action-id

    Action ID

    string

    query

    true

  • Example

    const resp = await fetch('https://api.holonym.io/sybil-resistance/gov-id/optimism?user=0x0000000000000000000000000000000000000000&action-id=12345678');
const { result: isUnique } = await resp.json();

  • Responses

    • 200

      {
    "result": true,
}

    • 200

      Result if user has not submitted a valid proof.

      {
    "result": false,
}

GET /residence/country/us/<network>?user=<user-address>

Get whether the user resides in the US.

For the /residence/country/<country-code> endpoints, <country-code> will be a 2-letter country code following the ISO 3166 standard. Holonym currently only supports queries for US residency.

  • Parameters

    namedescriptiontypeinrequired

    network

    'optimism' or 'optimism-goerli'

    string

    path

    true

    user

    User's blockchain address

    string

    query

    true

  • Example

    const resp = await fetch('https://api.holonym.io/residence/country/us/optimism?user=0x0000000000000000000000000000000000000000');
const { result: isUSResident } = await resp.json();

  • Responses

    • 200

      Result if user resides in the US.

      {
    "result": true,
}

    • 200

      Result if user has not submitted a valid proof that they reside in the US.

      {
    "result": false,
}

GET /snapshot-strategies/residence/country/us?network=<network>&snapshot=<snapshot>&addresses=<addresses>

Returns a list of scores indicating, for each address, whether the address has submitted a valid and unique proof of US residency.

Every score is either 1 or 0.

scoredescription

1

Address has proven US residency

0

Address has not proven US residency

Use with Snapshot

To use with the "api" Snapshot strategy, specify the strategy parameters using the following format.

{
  "api": "https://api.holonym.io",
  "symbol": "",
  "decimals": 0,
  "strategy": "snapshot-strategies/residence/country/us"
}

Use without Snapshot

  • Parameters

    namedescriptiontypeinrequired

    network

    Chain ID

    string

    query

    true

    snapshot

    Block height

    string

    query

    true

    addresses

    List of blockchain address separated by commas

    string

    query

    true

  • Example

    const resp = await fetch('https://api.holonym.io/snapshot-strategies/residence/country/us?network=420&snapshot=9001&addresses=0x0000000000000000000000000000000000000000,0x0000000000000000000000000000000000000001');
const data = await resp.json();

  • Responses

    • 200

      {
  "score" : [
      {
        "address" : "0x0000000000000000000000000000000000000000",
        "score" : 0
      },
      {
        "address" : "0x0000000000000000000000000000000000000001",
        "score" : 1
      }
  ]
}

GET /snapshot-strategies/sybil-resistance/gov-id?network=<network>&snapshot=<snapshot>&addresses=<addresses>&action-id=<action-id>

Returns a list of scores indicating, for each address, whether the address has submitted a valid proof of uniqueness for the given action-id.

Every score is either 1 or 0.

scoredescription

1

Address has proven uniqueness for action-id

0

Address has not proven uniqueness for action-id

Use with Snapshot

To use with the "api" Snapshot strategy, specify the strategy parameters using the following format. We highly recommend that projects use the default action-id 123456789 to avoid cases where users sell actions associated with action-ids that they do not care about.

{
  "api": "https://api.holonym.io",
  "symbol": "",
  "decimals": 0,
  "strategy": "snapshot-strategies/sybil-resistance/gov-id",
  "additionalParameters": "action-id=123456789"
}

Use without Snapshot

  • Parameters

    namedescriptiontypeinrequired

    network

    Chain ID

    string

    query

    true

    snapshot

    Block height

    string

    query

    true

    addresses

    List of blockchain address separated by commas

    string

    query

    true

  • Example

    const resp = await fetch('https://api.holonym.io/snapshot-strategies/sybil-resistance/gov-id?network=420&snapshot=9001&addresses=0x0000000000000000000000000000000000000000,0x0000000000000000000000000000000000000001&action-id=123');
const data = await resp.json();

  • Responses

    • 200

      {
  "score" : [
      {
        "address" : "0x0000000000000000000000000000000000000000",
        "score" : 0
      },
      {
        "address" : "0x0000000000000000000000000000000000000001",
        "score" : 1
      }
  ]
}

GET /snapshot-strategies/sybil-resistance/phone?network=<network>&snapshot=<snapshot>&addresses=<addresses>&action-id=<action-id>

Returns a list of scores indicating, for each address, whether the address has submitted a valid proof of uniqueness (using phone number) for the given action-id.

Every score is either 1 or 0.

scoredescription

1

Address has proven uniqueness for action-id

0

Address has not proven uniqueness for action-id

Use with Snapshot

To use with the "api" Snapshot strategy, specify the strategy parameters using the following format. We suggest that you use the default action-id 123456789. If you are using a different action-id, replace 123456789 with your action-id.

{
  "api": "https://api.holonym.io",
  "symbol": "",
  "decimals": 0,
  "strategy": "snapshot-strategies/sybil-resistance/phone",
  "additionalParameters": "action-id=123456789"
}

Use without Snapshot

  • Parameters

    namedescriptiontypeinrequired

    network

    Chain ID

    string

    query

    true

    snapshot

    Block height

    string

    query

    true

    addresses

    List of blockchain address separated by commas

    string

    query

    true

  • Example

    const resp = await fetch('https://api.holonym.io/snapshot-strategies/sybil-resistance/phone?network=420&snapshot=9001&addresses=0x0000000000000000000000000000000000000000,0x0000000000000000000000000000000000000001&action-id=123');
const data = await resp.json();

  • Responses

    • 200

      {
  "score" : [
      {
        "address" : "0x0000000000000000000000000000000000000000",
        "score" : 0
      },
      {
        "address" : "0x0000000000000000000000000000000000000001",
        "score" : 1
      }
  ]
}
PreviousCustom Sybil ResistanceNextSign Protocol Attestations

Last updated