---
name: irlslots
description: Use when the user wants to advertise at real-world events or to sell ad space on themselves or their things through IRLSlots. Covers finding events, creators and live ad slots, placing and managing bids, publishing auctions, chatting in a deal, uploading delivery proof and confirming completion. Requires an IRLSlots API key.
---

# IRLSlots

IRLSlots is a marketplace for real-world ad space: people wear or carry a brand's ad at
marathons, festivals, conferences and other events. Advertisers bid on ad slots; the winning
bid is charged, the creator shows the ad and uploads proof, and the advertiser confirms.
IRLSlots is free to list and bid on.

## Connect

IRLSlots exposes a remote MCP server over Streamable HTTP (stateless):

- URL: `https://irlslots.com/mcp`
- Header: `Authorization: Bearer <key>`

Create a key at `https://irlslots.com/settings/api`. Keys are scoped (`read`, `bid`, `sell`,
`messages`, `deliver`, `approve`) and carry per-key money limits (max bid, daily spend).
The same key works for the REST API at `https://irlslots.com/api/v1`
(OpenAPI: `https://irlslots.com/api/v1/openapi.json`).

Claude Code:

```
claude mcp add --transport http irlslots https://irlslots.com/mcp \
  --header "Authorization: Bearer <key>"
```

Any MCP client (`mcpServers` entry):

```json
{
  "mcpServers": {
    "irlslots": {
      "url": "https://irlslots.com/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}
```

## Tools

Read (scope `read`, always granted):

- `search_events` — find events by text, country, city, date range or category.
- `get_event` — one event plus the live placements on it.
- `search_listings` — browse live ad placements with the same filters as the website. Real
  auctions come first; example listings (`is_example: true`) are appended after them. Pass
  `include_examples: false` to get real auctions only.
- `get_listing` — one placement with photos, slots, hotspot zones, prices and auction end. A
  `demo-…` id returns `is_example: true` plus a `note`.
- `get_creator` — a creator's public profile and live placements.
- `my_profile` — the account behind the key, its scopes and money limits.
- `my_bids`, `my_deals`, `get_deal`, `listing_status`, `list_messages` — the account's own data.

List tools (`search_events`, `search_listings`, `my_bids`, `my_deals`, `list_messages`) share the
same pagination: `limit` 1–50 (default 20) plus either `page` (1-based) or the opaque `cursor`
from `pagination.next_cursor`. Every list response carries
`pagination: { page, limit, total, total_pages, next_cursor }`; `next_cursor` is `null` on the
last page. Example listings count toward `total` and come right after the real auctions.

Money and write tools (need the matching scope):

- `place_bid` (`bid`) — authorize a bid on a slot. Requires a unique `idempotency_key`.
- `request_upload_url` (`sell` for `slot_photo`/`logo`, `deliver` for `proof`).
- `create_listing_draft`, `update_listing`, `publish_listing` (`sell`).
- `send_message` (`messages`).
- `submit_proof` (`deliver`).
- `approve_delivery`, `open_dispute` (`approve`, off by default).

## Buyer scenario

1. `search_events` with the region and dates to shortlist events.
2. `search_listings` with the same filters (add `event` once known, `max_usd` for a budget).
3. `get_listing` on the best candidates for slots, sizes, zones and the minimum next bid;
   `get_creator` for reputation. Present 3–5 options with price, event and what is included.
4. Ask the user to confirm the slot and the exact amount. Explain that bidding authorizes
   (holds) the amount on the card and it is charged only if the auction is won.
5. `place_bid` with a fresh `idempotency_key`. The first bid on a slot needs a creative
   (text, image upload id, link, instructions) — ask the user for it.
6. If the result is `{ "status": "requires_action", "action_url": "..." }`, give the link to
   the user: only a person can pass 3-D Secure. Do not retry the bid.
7. On a win, use `list_messages` / `send_message` to coordinate; after delivery,
   `get_deal` to inspect proofs, then `approve_delivery` or `open_dispute` — only when the
   user explicitly says so.

## Seller scenario

1. `request_upload_url` with `kind="slot_photo"`, then PUT the image bytes to `upload_url`
   with an `image/*` content type; keep the returned upload id.
2. `search_events` (or ask for a slug) and `create_listing_draft` with the event, photos and
   hotspot slots, auction conditions and the proof plan.
3. `publish_listing` with `identity_confirmed=true`; add `cross_border_confirmed=true` when the
   event is in another country. Payouts must be set up first — if blocked with
   `payouts_required`, send the user to `https://irlslots.com/settings/payouts`.
4. `listing_status` for bids and the auction end; `list_messages` / `send_message` to talk to
   the winning advertiser.
5. On the event day, upload proof photos (`request_upload_url` with `kind="proof"` and the
   `deal_id`, then `submit_proof`) against the items the buyer expects.

## Rules

- Money: `place_bid`, `publish_listing`, `approve_delivery` and `open_dispute` move or release
  real money. Never call them without an explicit instruction from the user, and never raise
  the key's limits yourself. Always send a unique `idempotency_key` where the tool asks for one.
- `requires_action` means a human must open `action_url` (3-D Secure). Never claim the action
  succeeded before it does.
- `approve_delivery` releases the creator's payout and cannot be undone. Only confirm after the
  user has seen the proof.
- Proof: judge only what a photo actually shows (the ad on the agreed person/spot at the event,
  readable and matching the approved creative). Report missing or unclear evidence; never
  invent confirmation.
- `is_example: true` on a listing means it is an example of how a placement looks — not a real
  auction. Example auctions cannot be bid on, bought or won: `place_bid` on one fails with
  `example_listing` and nothing is authorised. Real auctions are always listed before examples.
- Bids cannot be placed on your own slots, and a bid must be above the minimum next bid and
  inside the key's max-bid and daily-spend limits.

## Errors and rate limits

- Per key: reads 60/min, writes 10/min, bids 20/hour. Over a limit the call fails with
  `RATE_LIMITED` (HTTP 429 on REST). Wait and retry once; never loop.
- `FORBIDDEN` — the key is missing the required scope; ask the user to grant it in
  Settings → API.
- `NOT_FOUND` — wrong id/slug or an object the account cannot access.
- `example_listing` — the slot belongs to an example listing (`is_example: true`); it is not a
  real auction and no bid is possible. Find a real auction instead.
- `BAD_REQUEST` — invalid input (for example a bid below the minimum).
- `TIMEOUT` / `INTERNAL` — transient. Retry once, then tell the user.
- On any failure, surface the code and message to the user instead of silently retrying money
  actions.