Communities

Currently only available on Sepolia and Holesky as we roll out the feature

Check availability

Check the availability of a single community cluster

GET /check/availability/:clusterName/:walletName

Example

Single check

curl https://api.clusters.xyz/v0.1/community/check/availability/mycommunity/foobar?testnet=true

Response

Single Check

{
  "name": "mycommunity/foobar",
  "isAvailable": true
}

---

Check requirements

Check if the community requirements for a specific wallet has been met for registration

GET /check/requirements/:clusterName?walletAddress=:walletName

Example

curl https://api.clusters.xyz/v0.1/community/check/requirements/mycommunity?walletAddress=0x123?testnet=true

Response

{
  "clusterName": "mycommunity",
  "walletAddress": "0x123",
  "isRequirementsMet": true
}

---

Registration

POST /v0.1/community/register

Either registers a free community clusters OR returns transaction data for registrations that require payment.

Name	Description
HEADER (bearer) Authorization	Authentication key from wallet
clusterName	The cluster name of the community being registered
walletName	The wallet name being registered under the community
chainId (optional)	If the price of a community cluster is USDC, a chainId should be passed so that the correct contracts are used when returning transaction data. It will default to mainnet.
walletAddress (optional)	If the registration sign up's are restricted to community owners, a wallet address needs to be included to know who to register the name to.

Free

Example

curl --request POST \
  --url 'https://api.clusters.xyz/v0.1/community/register?testnet=true' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abc123' \
  --data '{
  "clusterName": "mycommunity",
  "walletName": "foobar"
}'

Response

{ 
   "clusterName": "mycommunity",
   "walletName": "foobar"
}

EVM payment

Example

curl --request POST \
  --url 'https://api.clusters.xyz/v0.1/community/register?testnet=true' \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-KEY: abc123' \
  --data '{
  "clusterName": "mycommunity",
  "walletName": "foobar",
  "chainId": "11155111"
}'

Response

{
  "clusterName": string;
  "walletName": string;
  "transactionInfo": {
    "type": "evm",
    "transaction": {
      "to": string;
      "data": `0x${string}`;
      "value": string;
    }
  }
}

Usage

import { createWalletClient, custom } from 'viem'
import { sepolia } from 'viem/chains'

const url = 'https://api.clusters.xyz/v0.1/community/register?testnet=true';
const getRegister = await fetch(url, { 
  method: 'POST',
  headers: {
    'Content-type': 'application/json',
    'X-AUTH-KEY': 'abc123'
  },
  data: JSON.stringify({ clusterName, walletName })
})
const register = await getRegister.json();

const walletClient = createWalletClient({
  chain: sepolia,
  transport: custom(provider),
});

const { to, data, value } = register.transactionInfo.transaction;
const tx = await walletClient.sendTransaction({
  account,
  to,
  data,
  value
});

Solana Payment

Example

curl --request POST \
  --url 'https://api.clusters.xyz/v0.1/community/register?testnet=true' \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-KEY: abc123' \
  --data '{
  "clusterName": "mycommunity",
  "walletName": "foobar",
  "chainId": "11155111"
}'

Response

{
  "clusterName": string;
  "walletName": string;
  "transactionInfo": {
    "type": "solana",
    "transaction": {
      "data": string; // base64 string of serialized transactions
    }
  }
}

Usage

import * as web3 from '@solana/web3.js';

const message = web3.VersionedMessage.deserialize(
  Buffer.from(register.transactionInfo.transaction, 'base64'),
);
const transaction = new web3.VersionedTransaction(message);
const { signature } = await provider.signAndSendTransaction(
  transaction,
);

Error handling

Testnet only - We are in beta only phase of community clusters. You'll receive this error if testnet is not defined

{ error: "testnet_only" }

Community not found - If the specific cluster name is not a community

{ error: "not_found" }

Not a verified user - If sign ups are restricted to community owners and the auth key is not from an owner

{ error: "not_verified" }

No wallet address found - If sign ups are restricted to community owners and no wallet address was included in the body of the request

{ error: "no_walletAddress_found"}

Registration has not started yet - If sign ups for this community have not started yet

{ error: "not_active" }

Name is not available - If the name is taken

{ error: "not_available" }

Requirements have not been met - If the user registering the name has not met the requirements

{ error: "requirements_not_met" }

Invalid chain id - If the chain submitted in the request is invalid

{ error: "invalid_chain_id" }

---

Transaction Status

Checks the status of a transaction

GET /v0.1/community/tx/:tx

Example

curl https://api.clusters.xyz/v0.1/community/tx/0x123?testnet=true

Response

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

200

{
  "tx": "0x123",
  "status": "not_found"
}