Registration

Check availability

Check the availability of one or more clusters

GET /v0.1/register/check/:name

POST /v0.1/register/check

Name	Description
BODY	string[] - an array of names to check

Example

# Single check
curl https://api.clusters.xyz/v0.1/register/check/namethatdoesntexist

# Bulk Check
curl --request POST \
  --url https://api.clusters.xyz/v0.1/register/check \
  --header 'Content-Type: application/json' \
  --data '["foobar", "namethatdoesntexist"]'

Response

Single Check

{
  "name": "namethatdoesntexist",
  "isAvailable": true
}

Bulk Check

[
  {
    "name": "foobar",
    "isAvailable": false
  },
  {
    "name": "namethatdoesntexist",
    "isAvailable": true
  }
]

---

Register Transaction Data

POST /v0.1/register

Get the transaction data for registering a cluster so that a user can sign it

Name	Description
network	"1" "10" "56" "137" "8453" "81457" "17000" "42161" "43114" "11155111" "solana"
sender	The sender's address (EVM or Solana)
names	{ name: string; bidAmountWei?: string }[] bidAmountWei (optional) is always in ETH
referralAddress (optional)	An address that would get credit for this registration (EVM or Solana)

Ethereum - Mainnet

Example

curl --request POST \
  --url https://api.clusters.xyz/v0.1/register \
  --header 'Content-Type: application/json' \
  --data '{
  "network": "1",
  "sender": "0x0000000000000000000000000000000000000001",
  "names": [
    { "name": "namethatdoesntexist1" },
    { "name": "namethatdoesntexist2" }
  ]
}'

Response

200

{
  "gasToken": {
    "symbol": "ETH",
    "decimals": 18
  },
  "transactionData": {
    "to": "0x00000000000e1a99dddd5610111884278bdbda1d",
    "data": "0x40bee835000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000002386f26fc10000000000000000000000000000000000000000000000000000002386f26fc1000000000000000000000000000000000000000000000000000000000000000000026e616d6574686174646f65736e746578697374310000000000000000000000006e616d6574686174646f65736e74657869737432000000000000000000000000",
    "value": "20000000000000000"
  },
  "registrationFee": "20000000000000000",
  "bridgeFee": "0",
  "names": [
    {
      "name": "namethatdoesntexist1",
      "amount": "10000000000000000"
    },
    {
      "name": "namethatdoesntexist2",
      "amount": "10000000000000000"
    }
  ]
}

500

Names unavailable

{
  "status": 500,
  "error": "names_unavailable",
  "message": "1 or more names are unavailable"
}

Bridge Failure

{
  "status": 500,
  "error": "lz_quote_fail",
  "message": "lz quote failed. most likely caused by wallets having insufficient balances"
}

Ethereum - Bridging

Note: Make sure the sender has enough funds to cover the transaction or the endpoint will result in an error from the bridge.

Example

curl --request POST \
  --url https://api.clusters.xyz/v0.1/register \
  --header 'Content-Type: application/json' \
  --data '{
  "network": "56",
  "sender": "0x0000000000000000000000000000000000000001",
  "names": [
    { "name": "namethatdoesntexist1" },
    { "name": "namethatdoesntexist2" }
  ]
}'

Response

200

{
  "gasToken": {
    "symbol": "BNB",
    "decimals": 18
  },
  "transactionData": {
    "to": "0x00000000000e1a99dddd5610111884278bdbda1d",
    "data": "0xef76678a00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000010440bee835000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000e00b7847192c0000000000000000000000000000000000000000000000000000e00b7847192c0000000000000000000000000000000000000000000000000000000000000000026e616d6574686174646f65736e746578697374310000000000000000000000006e616d6574686174646f65736e746578697374320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000260003010021010000000000000000000000000000fde8000000000000000001c016f08e3258000000000000000000000000000000000000000000000000000000",
    "value": "1011176496282622517"
  },
  "registrationFee": "126126012000000000",
  "bridgeFee": "885050484282622517",
  "names": [
    {
      "name": "namethatdoesntexist1",
      "amount": "63063006000000000"
    },
    {
      "name": "namethatdoesntexist2",
      "amount": "63063006000000000"
    }
  ]
}

500

Names unavailable

{
  "status": 500,
  "error": "names_unavailable",
  "message": "1 or more names are unavailable"
}

Bridge Failure

{
  "status": 500,
  "error": "lz_quote_fail",
  "message": "lz quote failed. most likely caused by wallets having insufficient balances"
}

Solana

Example

curl --request POST \
  --url https://api.clusters.xyz/v0.1/register \
  --header 'Content-Type: application/json' \
  --data '{
  "network": "solana",
  "sender": "dead111111111111111111111111111111111111111",
  "names": [
    { "name": "namethatdoesntexist1" },
    { "name": "namethatdoesntexist2" }
  ]
}'

Response

Notice when using solana, transactionData is an array of transactions instead of a single object on other networks. This is because only one name is supported per transaction at the moment when using solana.

200

{
  "gasToken": {
    "symbol": "SOL",
    "decimals": "lamports"
  },
  "transactionData": [
    { ...Transaction },
    { ...Transaction }
  ],
  "registrationFee": "443581060",
  "bridgeFee": "0",
  "names": [
    {
      "name": "namethatdoesntexist1",
      "amount": "221790530"
    },
    {
      "name": "namethatdoesntexist2",
      "amount": "221790530"
    }
  ]
}

500

Names unavailable

{
  "status": 500,
  "error": "names_unavailable",
  "message": "1 or more names are unavailable"
}

Bridge Failure

{
  "status": 500,
  "error": "lz_quote_fail",
  "message": "lz quote failed. most likely caused by wallets having insufficient balances"
}

---

Trasaction Status

Checks the status of a transaction

GET /v0.1/register/tx/:tx

For now, if you registered more than one name in a transaction, it'll only give you the status of the first name. To enable testnet querying on Sepolia, add ?testnet=true to the end of the URL

Example

curl https://api.clusters.xyz/v0.1/register/tx/0xffea3b29c64016772b7d3194b3c3899a62191e654990b6e3393b410667102284

Response

type status = 'not_found' | 'pending' | 'bridging' | 'invalid' | 'lost_bid' | 'finalized'

200

{
  "tx": "0xffea3b29c64016772b7d3194b3c3899a62191e654990b6e3393b410667102284",
  "status": "finalized"
}