Skip to main content

Wallet Integration

A comprehensive guide for integrating Celestials multi-chain naming service into wallet applications.

Overview​

Celestials enables users to register human-readable names (like alice.i) that resolve to wallet addresses across multiple blockchain networks. This eliminates the need for users to share complex hexadecimal addresses and provides a unified identity system across supported chains.

API Endpoints:

Integration Patterns​

1. Resolve Celestial Names to Addresses​

Use Case: When users enter a celestial name like alice.i in wallet's "Send To" field.

curl https://api.celestials.id/api/resolver/primary_lookup \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "celestial_ids": ["alice.i", "bob.i"],
    "chain_id": "0xf043a"
  }'

Response:

{
  "primary_addresses": {
    "alice.i": "0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5",
    "bob.i": "0x123d35Cc6634C0532925a3b8D5c9e4b1e0e5e5"
  }
}

2. Display Celestial Names for Addresses​

Use Case: Show celestial names in transaction history, contact lists, or anywhere addresses are displayed.

curl https://api.celestials.id/api/resolver/primary_reverse_lookup \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": ["0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5"],
    "chain_id": "0xf043a"
  }'

Response:

{
  "primary_celestials": {
    "0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5": "alice.i"
  }
}

Supported Blockchain Networks​

Retrieve the list of currently supported chains:

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

Address Verification System​

Understanding address verification levels is essential for implementing secure integrations and maintaining user trust.

Verification Levels​

NOT_VERIFIED

  • Address added without cryptographic proof of ownership
  • Can be added by anyone to any celestial
  • Poses security risks for transactions
  • Requires user warnings in wallet interfaces

VERIFIED

  • Ownership confirmed through cryptographic signature validation
  • User has proven control of the private key
  • Validated using chain-specific signature schemes (ECDSA, Ed25519, etc.)
  • Trustworthy but not designated as the primary celestial for this address

PRIMARY

  • Represents the authoritative celestial for a specific address on a given chain
  • Only one celestial can hold PRIMARY status per address per chain
  • Automatically assigned when a celestial verifies an address
  • Previous PRIMARY celestials for the same address are downgraded to VERIFIED
  • Returned by primary lookup endpoints as the canonical celestial identity

Verification Methods​

Address verification supports both off-chain API-based flows and direct on-chain contract interactions. Both approaches require users to cryptographically sign a verification message demonstrating control of their address.

Security Recommendations​

For optimal security, wallets should exclusively use PRIMARY addresses when possible, or at minimum require VERIFIED status before processing transactions.

Support​

For technical questions, integration assistance, or testnet token requests, contact: support@celestials.id

API overview: https://celestials.id/docs/api-overview Interactive documentation: https://api.celestials.id/scalar