Skip to main content

Walkthrough

Celestials is a multi-chain naming service that allows users to register human-readable names and link them to addresses across different blockchain networks.

Overview​

With Celestials, users can:

  • Register unique celestial IDs (like hello_world.i)
  • Link these IDs to addresses across multiple supported chains
  • Verify ownership of linked addresses through cryptographic signatures
  • Resolve names to addresses and vice versa

Environments​

We provide two environments for development and production use:

EnvironmentBackendFrontendForma RPC
Productionapi.celestials.idcelestials.idrpc.forma.art
Stageapi.stage.celestials.idstage.celestials.idrpc.sketchpad-1.forma.art

When to Use Each Environment​

  • Production: Ready for live applications. No authorization required.
  • Stage: Recommended for testing changes without spending real TIA or waiting for auctions to finish. Feel free to contact us if you need test TIA tokens.

All APIs are OpenAPI compatible and can be explored through the Scalar links above.

Address Verification Status​

Understanding the verification levels for linked addresses:

  • NOT_VERIFIED: Address was linked to a Celestial ID without cryptographic verification. Ownership cannot be confirmed.
  • VERIFIED: Address was linked and the user provided a cryptographic signature, proving ownership.
  • PRIMARY: Address is verified and marked as the user's primary address for this Celestial ID.

Core API Endpoints​

1. Batch Lookup​

Resolve multiple Celestial IDs to addresses on specific chains.

Endpoint: POST /api/resolver/lookup

Docs: https://api.celestials.id/scalar#tag/resolver/post/api/resolver/lookup

Example Request:

curl https://api.celestials.id/api/resolver/lookup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "celestial_chain": [
      {
        "celestials_id": "lueveka",
        "chain_id": "0xf043a"
      }
    ]
  }'

Example Response:

{
  "addresses": [
    {
      "address": "0x149ee62a662996eee56cb9385002f5e31ef794e6",
      "status": "NOT_VERIFIED"
    }
  ]
}

2. Batch Reverse Lookup​

Find all celestial IDs associated with multiple specific addresses.

Endpoint: POST /api/resolver/reverse_lookup

Docs: https://api.celestials.id/scalar#tag/resolver/post/api/resolver/reverse_lookup

Example Request:

curl https://api.celestials.id/api/resolver/reverse_lookup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "chain_addresses": [
      {
        "address": "0x0000a78C054b03be49DaF6A05c772705F0710000",
        "chain_id": "0xf043a"
      }
    ]
  }'

Example Response:

{
  "celestial_ids": [
    [
      {
        "celestial_id": "lueveka_alt.i",
        "status": "VERIFIED"
      },
      {
        "celestial_id": "lueveka.i",
        "status": "PRIMARY"
      },
    ]
  ]
}

3. Primary Lookup​

Lookup addresses on specific chain using list of Primary Celestial IDs.

Endpoint: POST /api/resolver/primary_lookup

Docs: https://api.celestials.id/scalar#tag/resolver/post/api/resolver/primary_lookup

Example Request:

curl https://api.celestials.id/api/resolver/primary_lookup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "celestial_ids": [
      "blobfest.i",
      "lueveka_alt.i"
    ],
    "chain_id": "0xf043a"
  }'

Example Response:

{
  "primary_addresses": {
    "blobfest.i": "0x1a83faf6bd193f17f97a3b0542d764397ff96d34",
    "lueveka_alt.i": "0x0000a78c054b03be49daf6a05c772705f0710000"
  }
}

4. Primary Reverse Lookup​

Lookup Primary Celestial IDs for list of addresses on a specific chain.

Endpoint: POST /api/resolver/primary_reverse_lookup

Docs: https://api.celestials.id/scalar#tag/resolver/post/api/resolver/primary_reverse_lookup

Example Request:

curl https://api.celestials.id/api/resolver/primary_reverse_lookup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "addresses": [
      "0x1a83faf6bd193f17f97a3b0542d764397ff96d34",
      "0x0000a78c054b03be49daf6a05c772705f0710000"
    ],
    "chain_id": "0xf043a"
  }'

Example Response:

{
  "primary_celestials": {
    "0x0000a78c054b03be49daf6a05c772705f0710000": "lueveka_alt.i",
    "0x1a83faf6bd193f17f97a3b0542d764397ff96d34": "blobfest.i"
  }
}

5. Address Changes​

Returns the changes of the addresses. The changes are sorted by change id in ascending order and the last change id is returned as the head.

Endpoint: POST /api/resolver/changes

Docs: https://api.celestials.id/scalar#tag/resolver/post/api/resolver/changes

Example Request:

curl https://api.celestials.id/api/resolver/changes \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "chain_id": "0xf043a",
    "from_change_id": 1234,
    "limit": 100,
    "only_head": false,
    "with_images": true
  }'

Example Response:

{
  "changes": [
    {
      "address": "0x0000a78C054b03be49DaF6A05c772705F0710000",
      "celestial_id": "lueveka",
      "change_id": 1234,
      "image_url": "https://ipfs.io/ipfs/QmUi269vE25fagqhyMCCTNSoiW6x4LHCwwQb3keSrEXAmC",
      "status": "NOT_VERIFIED"
    }
  ],
  "head": 2345
}

6. Supported Chains​

Get a list of all currently supported blockchain networks.

Endpoint: GET /api/resolver/chains

Docs: https://api.celestials.id/scalar#tag/resolver/get/api/resolver/chains

Example Request:

curl https://api.celestials.id/api/resolver/chains

System Status and Monitoring​

Backend Status​

Monitor the health and synchronization status of our backend services.

Endpoint: GET /api/status

Docs: https://api.celestials.id/scalar#tag/status/get/api/status

Example Request:

curl https://api.celestials.id/api/status

Example Response:

{
  "processed_block_height": 9390983,
  "rpc_block_height": 9390987,
  "sync_status": "SYNCING"
}

The status endpoint provides:

  • processed_block_height: Last block processed by our indexer
  • rpc_block_height: Current block height from the RPC node
  • sync_status: Current synchronization state

Support​

For questions, issues, or to request test tokens for the stage environment, please contact our team. support@celestials.id

API Documentation​

Complete API documentation with interactive examples is available at: