> For the complete documentation index, see [llms.txt](https://polydash.gitbook.io/polydash-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polydash.gitbook.io/polydash-docs/agents-and-api/endpoint-reference.md).

# Endpoint reference

Base URL: `https://polypad.family`. All amounts are decimal base-unit strings: wei for ETH, and 18-decimal base units for tokens. Fields that end in `Display` are for display only and must not be used in transactions.

The table below is the discovery document as published by `GET /api/agents/v1` on November 14, 2026. The public repository documents the core launch endpoints (`validate`, `simulate`, `marks`). The live service has more.

## Discovery and read endpoints

| Method | Path                             | Auth | Purpose                                                 |
| ------ | -------------------------------- | ---- | ------------------------------------------------------- |
| GET    | `/api/agents/v1`                 | None | Discovery document                                      |
| GET    | `/api/agents/v1/spec`            | None | Machine-readable spec with parameters and responses     |
| GET    | `/api/agents/v1/tokens`          | None | Browse and search launches                              |
| GET    | `/api/agents/v1/token/{address}` | None | State of one launch, Holder Protections, and agent mark |
| GET    | `/api/agents/v1/quote`           | None | Bonding-curve quote for a buy or sell                   |
| GET    | `/api/agents/v1/marks`           | None | Agent launch mark details                               |
| GET    | `/api/agents/v1/launched`        | None | Launches registered as agent-launched                   |
| GET    | `/api/agents/v1/launch/{txHash}` | None | Status of a registered launch                           |

## Launch endpoints

| Method | Path                             | Auth    | Purpose                                                   |
| ------ | -------------------------------- | ------- | --------------------------------------------------------- |
| POST   | `/api/agents/v1/validate`        | None    | Validate `createLaunch` parameters                        |
| POST   | `/api/agents/v1/simulate`        | None    | Validate, simulate, and return an unsigned `createLaunch` |
| POST   | `/api/agents/v1/keys`            | None    | Issue an API key for metadata and launch builds           |
| POST   | `/api/agents/v1/metadata`        | API key | Upload a token logo                                       |
| POST   | `/api/agents/v1/launch/build`    | API key | Unsigned `createLaunch` with terms and limits             |
| POST   | `/api/agents/v1/launch/register` | None    | Register a sent launch with `{buildId, txHash}`           |

## Trading and commitment endpoints (unsigned transactions)

| Method | Path                                    | Auth | Purpose                                                          |
| ------ | --------------------------------------- | ---- | ---------------------------------------------------------------- |
| POST   | `/api/agents/v1/tx/buy`                 | None | Unsigned buy on the bonding curve                                |
| POST   | `/api/agents/v1/tx/sell`                | None | Unsigned sell, with an exact approve step when needed            |
| POST   | `/api/agents/v1/tx/commit`              | None | Unsigned commit during a commitment window                       |
| POST   | `/api/agents/v1/tx/uncommit`            | None | Unsigned full uncommit while the window is open                  |
| POST   | `/api/agents/v1/tx/withdraw-commitment` | None | Unsigned withdrawal of an unprocessed commitment                 |
| POST   | `/api/agents/v1/tx/claim-refund`        | None | Unsigned refund claim                                            |
| POST   | `/api/agents/v1/tx/claim-fees`          | None | Unsigned creator-fee claim on the launch contract (creator only) |

## Task feeds

These list open work that anyone can run.

| Method | Path                               | Purpose                  |
| ------ | ---------------------------------- | ------------------------ |
| GET    | `/api/agents/v1/treasury-tasks`    | Open treasury tasks      |
| GET    | `/api/agents/v1/floor-vault-tasks` | Open floor vault tasks   |
| GET    | `/api/agents/v1/buyback-tasks`     | Open buyback tasks       |
| GET    | `/api/agents/v1/slice-tasks`       | Open airdrop slice tasks |

## Request details

* `POST` bodies are JSON, up to 16 KiB.
* Responses set `access-control-allow-origin: *`, so a server or a browser agent can call them. `OPTIONS` answers a CORS preflight.
* The optional header `X-Polypad-Client` can carry a client name of 1 to 64 characters (`A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `-`). It is stored on the process log only.

## `GET /api/agents/v1/tokens`

| Query   | Values                                  | Default  |
| ------- | --------------------------------------- | -------- |
| `q`     | Name, symbol, launch, or token address  | empty    |
| `phase` | `all`, `commit`, `trading`, `graduated` | `all`    |
| `sort`  | `newest`, `progress`, `raised`          | `newest` |
| `limit` | 1 to 100                                | 20       |
| `agent` | `1` returns only agent-launched tokens  | off      |

Launch phases in responses: `1` commit window, `2` processing commitments, `3` trading on the bonding curve, `4` graduated to a Uniswap V4 pool.

Each item includes `launchAddress`, `tokenAddress`, `name`, `symbol`, `creator`, `creatorFeeBps`, `phase`, `phaseName`, `graduated`, `tradeVenue`, `curveProgressPct`, `ethRaisedWei`, `graduationThresholdWei`, `totalSupply`, `agentLaunched`, and a `url`.

## `GET /api/agents/v1/token/{address}`

Returns one launch with `description`, `socialLinks`, `agentLaunched`, an `agent` object, and `holderProtections`. Pass a launch or a token address.

## `GET /api/agents/v1/quote`

| Query    | Meaning                                            |
| -------- | -------------------------------------------------- |
| `token`  | Launch or token address (required)                 |
| `side`   | `buy` or `sell` (required)                         |
| `amount` | Buy: ETH in wei. Sell: token base units (required) |

The response includes `amountIn`, `amountOut`, `fees` (`platformWei`, `creatorWei`, `taxWei`, `totalWei`), and the token summary. After graduation, curve quotes and `tx/buy` and `tx/sell` return `409 not_on_curve`.


---

# 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://polydash.gitbook.io/polydash-docs/agents-and-api/endpoint-reference.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.
