# Communities

{% hint style="info" %}
Currently only available on Sepolia and Holesky as we roll out the feature
{% endhint %}

## Check availability

Check the availability of a single community cluster

<mark style="color:green;">`GET`</mark> `/check/availability/:clusterName/:walletName`

**Example**

{% code title="Single check" %}

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

{% endcode %}

**Response**

{% tabs %}
{% tab title="Single Check" %}

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

{% endtab %}
{% endtabs %}

***

## Check requirements

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

<mark style="color:green;">`GET`</mark> `/check/requirements/:clusterName?walletAddress=:walletName`

**Example**

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

**Response**

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

***

## Registration

<mark style="color:green;">`POST`</mark> `/v0.1/community/register`

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

<table><thead><tr><th width="226">Name</th><th>Description</th></tr></thead><tbody><tr><td>HEADER <em>(bearer)</em> <code>Authorization</code></td><td><a href="/pages/GvLe79HZ0PXI5WTSVCdV#authentication">Authentication key from wallet</a></td></tr><tr><td><code>clusterName</code></td><td>The cluster name of the community being registered</td></tr><tr><td><code>walletName</code></td><td>The wallet name being registered under the community</td></tr><tr><td><code>chainId</code><br><em>(optional)</em></td><td>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.</td></tr><tr><td><code>walletAddress</code><br><em>(optional)</em></td><td>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.</td></tr></tbody></table>

{% tabs %}
{% tab title="Free" %}
**Example**

```bash
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**

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

{% endtab %}

{% tab title="EVM payment" %}
**Example**

```bash
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**

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

**Usage**

```typescript
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
});
```

{% endtab %}

{% tab title="Solana Payment" %}
**Example**

```bash
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**

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

**Usage**

```typescript
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,
);
```

{% endtab %}

{% tab title="Error handling" %}
**Testnet only -** We are in beta only phase of community clusters. You'll receive this error if testnet is not defined

```json
{ 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" }
```

{% endtab %}
{% endtabs %}

***

## Transaction Status

Checks the status of a transaction

<mark style="color:green;">`GET`</mark> `/v0.1/community/tx/:tx`

**Example**

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

**Response**

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

{% tabs %}
{% tab title="200" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clusters.xyz/getting-started/api/v0.1-deprecated/communities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.