API domain integration

This part of the documentation explains how to resolve a domain, address, or read identity information via the API. We do not recommend calling our endpoint to avoid centralization. It was designed for the StarknetId product. If you want to use it anyway it is highly recommended to selfhost it.

🔗 View the source code on GitHub (opens in a new tab)

Endpoints

Domain to Address

Retrieve the associated address and its expiry date for a given domain.

Method & URL

HTTP Method: GET
API URL: https://api.starknet.id/domain_to_addr

Query Parameters

Name	Type	Description
`domain`	`string`	The domain to query

Response

The API will return the associated address along with its expiry date.

Example request

https://api.Starknet.id/domain_to_addr?domain=fricoben.stark

Success Response Example

{
  "addr": "0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3",
  "domain_expiry": 1796569200
}

Error Response Example

no address found

Address to Domain

Retrieve the associated domain and its expiry date for a given address.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/addr_to_domain

Query Parameters

Name	Type	Description
`addr`	`string`	The address to query

Response

The API will return the associated domain along with its expiry date.

Example request

https://api.Starknet.id/addr_to_domain?addr=0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3

Success Response Example

{
  "domain": "fricoben.stark",
  "domain_expiry": 1796569200
}

Error Response Example

No domain found

Addresses to Domains

Retrieve the associated domains for multiple addresses in a single request. This is particularly useful for applications like leaderboards or blockchain explorers where multiple addresses need to be resolved to their respective domains efficiently.

Method & URL

HTTP Method: POST
API URL: https://api.Starknet.id/addrs_to_domains

Request Body

The request body should be a JSON object containing a list of addresses under the key addresses.

Example Request Body

{
  "addresses": [
    "0x048F24D0D0618fa31813DB91a45d8be6c50749e5E19ec699092CE29aBe809294",
    "0x00a00373A00352aa367058555149b573322910D54FCDf3a926E3E56D0dCb4b0c",
    "0x00B325463D0dDCa69Bb6234CD6FCA161b35035F14386b6403a9De208E5a1C71b"
  ]
}

Response

The API will return a list of objects, each containing a domain and its associated address. If a domain is not found for an address, the domain key will be null.

Success Response Example

[
  {
    "domain": "th0rgal.stark",
    "address": "0x00a00373a00352aa367058555149b573322910d54fcdf3a926e3e56d0dcb4b0c"
  },
  {
    "domain": "asjosaok23.stark",
    "address": "0x048f24d0d0618fa31813db91a45d8be6c50749e5e19ec699092ce29abe809294"
  },
  {
    "domain": null,
    "address": "0x00b325463d0ddca69bb6234cd6fca161b35035f14386b6403a9de208e5a1c71b"
  }
]

Error Response Example

Failed to parse the request body as JSON: addresses[1]: control character (\u0000-\u001F) found while parsing a string at line 5 column 0

Address to External Domains

Retrieve the braavos and xplorer subdomain associated to an address.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/addr_to_external_domains

Query Parameters

Name	Type	Description
`addr`	`string`	The address to query

Response

The API will return the associated braavos and xplorer subdomains.

Example request

https://api.Starknet.id/addr_to_domain?addr=0x061b6c0a78f9edf13cea17b50719f3344533fadd470b8cb29c2b4318014f52d3

Success Response Example

{
  "domains": ["fricoben.braavos.stark"]
}

Empty Response Example

{
  "domains":[]
}

Address to Starknet IDs

Retrieve all the Starknet IDs owned by a given address.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/addr_to_full_ids

Query Parameters

Name	Type	Description
`addr`	`string`	The address to query

Response

The API will return all the Starknet IDs owned by the address.

Example request

https://api.Starknet.id/addr_to_full_ids?addr=0x072D4F3FA4661228ed0c9872007fc7e12a581E000FAd7b8f3e3e5bF9E6133207

Success Response Example

{
  "full_ids": [
    { "id": "694846134574" },
    { "id": "846904695223" },
    { "id": "718722140035", "domain": "deployer.fricoben.stark" },
    { "id": "4799954900", "domain": "domaintesttest.stark" },
    { "id": "23365742225" },
    { "id": "289323426116", "domain": "treasuryship.stark" }
  ]
}

Empty Response Example

https://api.Starknet.id/addr_to_full_ids?addr=0x00Ec0ED6E46a4435C6324D47EADeaadFBc9f66D372F4Cf36b767F5F26754bB47

{
  "full_ids": []
}

Error Response Example

https://api.Starknet.id/addr_to_full_ids?addr=lol.stark

Failed to deserialize query string: invalid character

Address to Available Starknet IDs

Retrieve available (not associated with a domain) Starknet IDs owned by a given address.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/addr_to_available_ids

Query Parameters

Name	Type	Description
`addr`	`string`	The address to query

Response

The API will return all the Starknet IDs that are not linked with a domain yet owned by the address.

Example request

https://api.Starknet.id/addr_to_available_ids?addr=0x072D4F3FA4661228ed0c9872007fc7e12a581E000FAd7b8f3e3e5bF9E6133207

Success Response Example

{
  "ids": ["694846134574", "846904695223", "23365742225"]
}

Empty Response Example

{
  "ids": []
}

Error Response Example

https://api.starknet.id/addr_to_available_ids?addr=lol.stark

Failed to deserialize query string: invalid character

Address to token id

Retrieve the token ID associated with a given address.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/addr_to_token_id

Query Parameters

Name	Type	Description
`addr`	`string`	The address to query

Response

The API will retrieve the token id of the Starknet ID associated with the main domain of the address.

Example request

https://api.Starknet.id/addr_to_token_id?addr=0x072D4F3FA4661228ed0c9872007fc7e12a581E000FAd7b8f3e3e5bF9E6133207

Success Response Example

{
  "token_id": "718722140035"
}

Error Response Example

https://api.Starknet.id/addr_to_token_id?addr=0x00Ec0ED6E46a4435C6324D47EADeaadFBc9f66D372F4Cf36b767F5F26754bB47

no main domain found for this address

Token id to data

Retrieve the data of a Starknet ID.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/id_to_data

Query Parameters

Name	Type	Description
`id`	`string`	The id to query

Response

The API will retrieve the data written on the Starknet ID. If a domain is held by this id, domain will contain all its naming data. verifier_data and extended_verifier_data will contain identity data written through other smartcontracts. This data space is permissionless so it usually requires some interpretation to make sense, it could be twitter id, discord id, profile pics or anything else.

Example request

https://api.Starknet.id/id_to_data?id=1

Success Response Example

{
  "id": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "owner": "0x00a00373a00352aa367058555149b573322910d54fcdf3a926e3e56d0dcb4b0c",
  "main": true,
  "creation_date": 1669055689,
  "domain": {
    "domain": "th0rgal.stark",
    "migrated": true,
    "root": true,
    "creation_date": 1669721226,
    "expiry": 1732793226,
    "resolver": null,
    "legacy_address": "0x00a00373a00352aa367058555149b573322910d54fcdf3a926e3e56d0dcb4b0c",
    "rev_address": null
  },
  "user_data": [],
  "verifier_data": [
    {
      "verifier": "0x06ac597f8116f886fa1c97a23fa4e08299975ecaf6b598873ca6792b9bbfb678",
      "field": "0x000000000000000000000000000000000000000000000000000000006e616d65",
      "data": "0x01906b81b516288254d766bf5b743582ce3821769f4cc5e27a7dd73db94b4255"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x0000000000000000000000000000000000000000000000000000676974687562",
      "data": "0x00000000000000000000000000000000000000000000000000000000027e4773"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x0000000000000000000000000000000000000000000000000000676974687562",
      "data": "0x00000000000000000000000000000000000000000000000000000000027e4773"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x00000000000000000000000000000000000000000000000000646973636f7264",
      "data": "0x0000000000000000000000000000000000000000000000000fcdaf97ff043001"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x00000000000000000000000000000000000000000000000000646973636f7264",
      "data": "0x00000000000000000000000000000000000000000000000009d33f313202005d"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x0000000000000000000000000000000000000000000000000074776974746572",
      "data": "0x0000000000000000000000000000000000000000000000000af4c5d88c167000"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x0000000000000000000000000000000000000000000000000074776974746572",
      "data": "0x0000000000000000000000000000000000000000000000000af4c5d88c167000"
    },
    {
      "verifier": "0x070aaa20ec4a46da57c932d9fd89ca5e6bb9ca3188d3df361a32306aff7d59c7",
      "field": "0x00000000000000000000000000000000006e66745f70705f636f6e7472616374",
      "data": "0x03ab1124ef9ec3a2f2b1d9838f9066f9a894483d40b33390dda8d85c01a315a3"
    }
  ],
  "extended_verifier_data": [
    {
      "verifier": "0x070aaa20ec4a46da57c932d9fd89ca5e6bb9ca3188d3df361a32306aff7d59c7",
      "field": "0x00000000000000000000000000000000000000000000006e66745f70705f6964",
      "extended_data": [
        "0x0000000000000000000000000000000000000000000000000000000000001b98",
        "0x0000000000000000000000000000000000000000000000000000000000000000"
      ]
    }
  ]
}

Error Response Example

https://api.Starknet.id/id_to_data?id=10123891239013292

Identity not found

Domain to data

Retrieve the data of a domain.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/domain_to_data

Query Parameters

Name	Type	Description
`domain`	`string`	The domain to query

Response

Like the previous endpoint, API will retrieve everything related to an identity but via its associated domain.

Example request

https://api.Starknet.id/domain_to_data?domain=fricoben.stark

Success Response Example

{
  "id": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "owner": "0x00a00373a00352aa367058555149b573322910d54fcdf3a926e3e56d0dcb4b0c",
  "main": true,
  "creation_date": 1669055689,
  "domain": {
    "domain": "th0rgal.stark",
    "migrated": true,
    "root": true,
    "creation_date": 1669721226,
    "expiry": 1732793226,
    "resolver": null,
    "legacy_address": "0x00a00373a00352aa367058555149b573322910d54fcdf3a926e3e56d0dcb4b0c",
    "rev_address": null
  },
  "user_data": [],
  "verifier_data": [
    {
      "verifier": "0x06ac597f8116f886fa1c97a23fa4e08299975ecaf6b598873ca6792b9bbfb678",
      "field": "0x000000000000000000000000000000000000000000000000000000006e616d65",
      "data": "0x01906b81b516288254d766bf5b743582ce3821769f4cc5e27a7dd73db94b4255"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x0000000000000000000000000000000000000000000000000000676974687562",
      "data": "0x00000000000000000000000000000000000000000000000000000000027e4773"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x0000000000000000000000000000000000000000000000000000676974687562",
      "data": "0x00000000000000000000000000000000000000000000000000000000027e4773"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x00000000000000000000000000000000000000000000000000646973636f7264",
      "data": "0x0000000000000000000000000000000000000000000000000fcdaf97ff043001"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x00000000000000000000000000000000000000000000000000646973636f7264",
      "data": "0x00000000000000000000000000000000000000000000000009d33f313202005d"
    },
    {
      "verifier": "0x002d5f0f2fcba62a54f0d8a73fb2e437d76c53f7297153b2afd1f198af6d12aa",
      "field": "0x0000000000000000000000000000000000000000000000000074776974746572",
      "data": "0x0000000000000000000000000000000000000000000000000af4c5d88c167000"
    },
    {
      "verifier": "0x0480258f58d43fb73936f803780047a0f6d0a563697d80bd3f95b603f9c8b1c8",
      "field": "0x0000000000000000000000000000000000000000000000000074776974746572",
      "data": "0x0000000000000000000000000000000000000000000000000af4c5d88c167000"
    },
    {
      "verifier": "0x070aaa20ec4a46da57c932d9fd89ca5e6bb9ca3188d3df361a32306aff7d59c7",
      "field": "0x00000000000000000000000000000000006e66745f70705f636f6e7472616374",
      "data": "0x03ab1124ef9ec3a2f2b1d9838f9066f9a894483d40b33390dda8d85c01a315a3"
    }
  ],
  "extended_verifier_data": [
    {
      "verifier": "0x070aaa20ec4a46da57c932d9fd89ca5e6bb9ca3188d3df361a32306aff7d59c7",
      "field": "0x00000000000000000000000000000000000000000000006e66745f70705f6964",
      "extended_data": [
        "0x0000000000000000000000000000000000000000000000000000000000001b98",
        "0x0000000000000000000000000000000000000000000000000000000000000000"
      ]
    }
  ]
}

Error Response Example

https://api.Starknet.id/domain_to_data?domain=qqqqqqqqqs.stark

Identity not found

Data to token ids

SOON Available

Uri

Retrieve the NFT uri of a Starknet ID.

Method & URL

HTTP Method: GET
API URL: https://api.Starknet.id/uri

Query Parameters

Name	Type	Description
`id`	`string`	The id to query

Response

The API will retrieve the uri of the Starknet ID NFT.

Example request

https://api.Starknet.id/uri?id=12

Success Response Example

{
  "name": "66868.stark",
  "description": "This token represents an identity on Starknet.",
  "image": "https://Starknet.id/api/identicons/12",
  "expiry": 1702361677,
  "attributes": [
    { "trait_type": "Subdomain", "value": ["yes"] },
    { "trait_type": "Domain expiry", "value": ["Dec 12, 2023"] },
    { "trait_type": "Domain expiry timestamp", "value": ["1702361677"] }
  ]
}

Inexistant Starknet ID Response Example

https://api.Starknet.id/uri?id=1627381236172

{
  "name": "Starknet ID: 1627381236172",
  "description": "This token represents an identity on Starknet.",
  "image": "https://Starknet.id/api/identicons/1627381236172",
  "expiry": null,
  "attributes": null
}

Starknetid.rs Deployed Contracts