> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/integration-guides/manage-guilds.md).

# Manage Guilds and Guild Duels

Guilds group master accounts (L1 addresses) into communities with a leader, admins and members. Guild endpoints use the `/api/v1/guild` prefix.

Guilds and Guild Duels are not supported on Robinhood Chain.

## Authentication

* Read endpoints (`guild`, `guild/list`, `guild/leaderboard`, `guild/byReferralCode`, `guild/duel`, `guild/duel/list`, `guild/duel/metrics`) are public.
* Every other endpoint takes `account_index` plus an auth token: either the `Authorization` header or the `auth` query/form parameter (see [API keys: Authentication](https://docs.lighter.xyz/developers/integration-guides/api-keys.md#authentication) for the token format). The token must belong to `account_index`; the account's **L1 address** is what joins, leads or is invited. Any account of the same owner (master or sub-account) can be used, the action is always applied to the owner.
* `POST` endpoints take their parameters as form fields (`application/x-www-form-urlencoded`), like the other `POST` endpoints of the API.

## Guild lifecycle

Guild creation is currently restricted to whitelisted addresses approved by the Lighter team.

1. **Discover.** `GET /api/v1/guild/list` lists guilds; `GET /api/v1/guild/leaderboard` returns the guild ladder. `GET /api/v1/guild?guild_id=…` returns a guild, its members and 30-day stats. Add `include_positions=true` to include aggregated open positions.
2. **Check membership.** `GET /api/v1/guild/membership` (authenticated) returns the caller's `status` (`member|invited|requested|none`), role, guild and pending requests/invites.
3. **Request to join.** For a guild with `accepts_join_requests=true`, call `POST /api/v1/guild/join/request`. A leader or admin reviews the request in the app. Requests expire after 7 days. An account already in a guild must leave before joining another one.
4. **Resolve a referral.** `GET /api/v1/guild/byReferralCode?code=…` resolves a referral code to its owner's guild (empty `200` if none). Pass `source=referral_prompt` on the join request to attribute it.
5. **Leave.** Call `POST /api/v1/guild/leave`. A leader must transfer leadership in the app before leaving (`42021`). Joining a guild voids the account's other pending requests and invites.

Guild creation, editing, archiving, invite codes, request withdrawal and review, member removal, and role management are handled in the app.

## Guild duels

Only guild leaders can challenge another guild, respond to an offer or report a stake (`42009` otherwise).

1. **Choose a metric.** `GET /api/v1/guild/duel/metrics` returns the allowed metrics (`median_roi`, `guild_roi`, `pnl`, `volume`, `roi_sqrt_volume`).
2. **Challenge.** Call `POST /api/v1/guild/duel/challenge` with `target_guild_id` and the terms. Terms are validated (`42032`) against: stake 100–100,000 USDC (`stake_amount` in USDC × 10⁶, i.e. `100000000`–`100000000000`); `start_time` in ms, aligned to the hour, > now + 24h and ≤ now + 30 days; `duration_secs` ∈ {86400, 259200, 604800, 1209600}; `1 ≤ min_members ≤ max_members of the smaller guild`; `message` ≤ 280 chars. Limits: 5 open outgoing proposals per guild (`42043`), one pending challenge per target (`42042`), no challenge while either guild has a committed duel (`42027`/`42028`).
3. **Respond.** Call `POST /api/v1/guild/duel/accept` or `POST /api/v1/guild/duel/decline` for the pending offer. Only the side that did not author the pending offer can respond (`42030`). Offers expire after 48h (`expires_at`), capped so acceptance still leaves a 24h funding window before `start_time`. On acceptance, both rosters lock and are topped up to `min_members` (opted-in members first, then random).
4. **Stake.** After `accepted`, `GET /api/v1/guild/myDuel` returns `stake_info` (`escrow_account_index`, `amount`, `memo`, `funding_deadline`). Each leader sends a normal L2 **USDC transfer** (see [Transfer between Lighter accounts](https://docs.lighter.xyz/developers/integration-guides/deposits-transfers-and-withdrawals.md#transfer-between-lighter-accounts)) of exactly `amount` from one of their accounts to `escrow_account_index`, with `memo` = hex `sha256("guildduel:<duel_id>")` as returned, then reports the executed tx with `POST /api/v1/guild/duel/stake` (`tx_hash`). Transfer must be executed (`42037`), exact amount from the leader (`42034`), memo must match (`42035`). A transfer carrying the memo that can no longer be the stake (late, wrong amount, duel no longer accepted, already staked) is answered `42040` and queued for refund. When both sides are confirmed the duel becomes `funded`; it goes `live` at `start_time`, `finished` after `end_time` (scored \~2h later) and `settled` once payouts (`kind=payout` to the winner's leader account, or `kind=refund` to both on a tie / void) are confirmed on-chain. No fee is taken from the pot.
5. **Read.** `GET /api/v1/guild/duel?duel_id=…` and `GET /api/v1/guild/duel/list` are public and only return duels in `funded|live|finished|settled`. Proposals are visible to the two guilds through authenticated `GET /api/v1/guild/myDuels` and `GET /api/v1/guild/myDuel`. `score` and `scores` are refreshed hourly while live and final once finished.

Counteroffers, cancellation, roster editing and member availability preferences are handled in the app. While duels are switched off (`42038`), declining an offer remains available through the API so open negotiations can be closed.

## Error codes

See [Data Structures, Constants and Errors](https://docs.lighter.xyz/developers/reference/data-structures-constants-and-errors.md#full-error-list) for the Guilds and Guild Duels business errors (`42001`–`42044`; `42007` is not defined).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lighter.xyz/developers/integration-guides/manage-guilds.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
