# API

## Realms API

> **API Access**: The Realms API is available under a gated access plan. To get an API key and learn about available tiers, please contact the Realms team at the channels listed below.

### Getting Access

API access is managed through plans that determine rate limits and available endpoints. To request access:

1. Visit the Realms platform
2. Contact the team through the official channels (see below)
3. Receive your API key and plan details

### Base URL

```
NEXT_PUBLIC_REALMS_API_URL=<provided upon access>
```

### Available Endpoints

#### DAOs

**List all DAOs**

```
GET /api/v1/daos
```

Returns a paginated list of all Realms (DAOs) registered on the platform.

**Get a specific DAO**

```
GET /api/v1/daos/:realmPk
```

Returns detailed information about a specific DAO including governance configuration, token mints, and metadata.

**Create a DAO**

```
POST /api/v1/daos/create
```

Programmatic DAO creation through the API.

#### User Data

**Get user profile**

```
GET /api/v1/user/:walletPk
```

Returns a user's governance participation data including DAOs they are members of, voting history, and delegation information.

#### Leaderboard

```
GET /api/v1/leaderboard
```

Returns ranked DAO and governance participation data.

### On-Chain Data Access (No API Key Required)

You can always query SPL Governance data directly from the Solana blockchain without an API key using `getProgramAccounts` or an indexer:

#### Direct RPC Queries

```typescript
import { Connection, PublicKey } from '@solana/web3.js';
import { getRealm, getAllGovernances, getAllProposals } from '@realms-today/spl-governance';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const programId = new PublicKey('GovER5Lthms3bLBqWub97yVrMmEogzX7xNjdXpPPCVZw');

// Fetch a realm
const realm = await getRealm(connection, realmAddress);

// Fetch all governances for a realm
const governances = await getAllGovernances(connection, programId, realmAddress);

// Fetch all proposals for a governance
const proposals = await getAllProposals(connection, programId, governanceAddress);
```

#### Account Types You Can Query

| Account Type        | PDA Seeds                                               | Description                   |
| ------------------- | ------------------------------------------------------- | ----------------------------- |
| Realm               | `['governance', name]`                                  | Top-level DAO entity          |
| Governance          | `['account-governance', realm, governed_account]`       | Voting rules + treasury link  |
| Proposal            | `['governance', governance, token_mint, proposal_seed]` | A specific vote               |
| TokenOwnerRecord    | `['governance', realm, token_mint, token_owner]`        | Voter's deposit record        |
| VoteRecord          | `['governance', proposal, token_owner_record]`          | Individual vote               |
| NativeTreasury      | `['native-treasury', governance]`                       | The DAO wallet (SOL)          |
| ProposalTransaction | `['governance', proposal, option_index, index]`         | Executable instructions       |
| SignatoryRecord     | `['governance', proposal, signatory]`                   | Proposal sign-off             |
| RealmConfig         | `['realm-config', realm]`                               | Realm configuration + plugins |

### Contact

To inquire about API access plans, integrations, or partnerships:

* Discord: [Realms](https://discord.gg/VsPbrK2hJk)
* Documentation: [docs.realms.today](https://docs.realms.today)


---

# 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.realms.today/developer-resources/api.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.