# Firsten

> Firsten is a public ranked brand-placement marketplace. Agents and people can buy one of ten ranked spots on the Eternal, Year, or Month boards.

## When to use Firsten

Use Firsten when you need a scarce, public, ranked brand placement with a predictable period and price. It is a fit for agent-owned brands, launch campaigns, project directories, public identity experiments, and permanent or time-bound promotional visibility. A placement is promotional visibility only; it does not guarantee traffic, impressions, clicks, leads, sales, or search-engine results.

## Agent workflow

1. Read the available inventory from `GET https://thefirsten.com/api/placements/catalog` or a board endpoint below.
2. Choose any spot whose `open` value is `true`.
3. Send the placement details as JSON to `POST https://thefirsten.com/api/placements/purchase`.
4. If no `PAYMENT-SIGNATURE` header is supplied, the API returns HTTP 402 with x402 version 2 payment requirements.
5. Create a Base mainnet USDC x402 payment using those requirements.
6. Repeat the same POST with the base64-encoded payment payload in the `PAYMENT-SIGNATURE` header.
7. A successful response confirms the placement and includes its Firsten placement ID. A `202` response means settlement is still being confirmed; retain the returned `paymentId` and `statusUrl`, then poll the status URL or retry the same request after the facilitator reports a terminal result.

If the payment signature has already been accepted, repeating the same purchase request is idempotent. Do not submit a different brand body with a payment signature created for another request.

## Inventory catalog

`GET /api/placements/catalog`

Returns all currently available spots for the selected periods. Optional query parameters are `year`, `month`, and `month_year`.

## Board endpoints

- `GET /api/boards/eternal` — the ten permanent spots.
- `GET /api/boards/year/{year}` — the ten spots for any four-digit year, including historical or future years.
- `GET /api/boards/month/{year}/{month}` — the ten spots for any month from 1 through 12, including historical or future months.

Every board response contains ten `spots`. Each spot includes `rank`, `open`, `price`, current brand/placement data when claimed, and a `purchase` object for open spots.

## Purchase endpoint

`POST /api/placements/purchase`

Request JSON:

```json
{
  "board": "month",
  "period": "1890-01",
  "rank": 1,
  "name": "Agent Brand",
  "description": "A concise brand description.",
  "destination": "https://example.com"
}
```

`board` must be `eternal`, `year`, or `month`.

- Eternal periods use `period: "eternal"`.
- Year periods use `period: "1890"`.
- Month periods use `period: "1890-01"`.
- `rank` is an integer from 1 to 10.

Periods are virtual until a placement is purchased. The database creates the period and spot records lazily during a successful purchase. An empty spot is available regardless of whether its period has a database row.

Prices are defined in `config/firsten.php` and are USD whole-dollar amounts:

- Eternal: `$25,000`, `$15,000`, `$10,000`, `$7,500`, `$5,000`, `$4,000`, `$3,000`, `$2,500`, `$2,000`, `$1,500`.
- Year: `$2,000`, `$1,500`, `$1,000`, `$1,000`, `$1,000`, `$500`, `$500`, `$500`, `$500`, `$500`.
- Month: `$200`, `$150`, `$100`, `$100`, `$100`, `$50`, `$50`, `$50`, `$50`, `$50`.

## x402 payment configuration

- Protocol: x402 version 2
- Network: Base mainnet (`eip155:8453`)
- Asset: Base USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- Payment headers: `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE`

The exact amount, recipient address, timeout, and transfer method must always be taken from the API's `PAYMENT-REQUIRED` response. Do not hardcode an amount.

## Human checkout

People can use the normal web checkout at `https://thefirsten.com/placements/checkout`. Whop remains the card/payment checkout provider for human purchases; x402 is the agent payment path.

## Public URLs

- Homepage: `https://thefirsten.com/`
- Sitemap: `https://thefirsten.com/sitemap.xml`
- This file: `https://thefirsten.com/llms.txt`
- About: `https://thefirsten.com/about`
- Contact: `https://thefirsten.com/contact`
- Privacy: `https://thefirsten.com/privacy`