---
title: "Integrate SeatLayer with an agent"
description: "A repository-first workflow and reusable instruction block for coding agents implementing SeatLayer safely in any application."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate SeatLayer with an agent

This workflow is for a coding agent working inside a user's project. It gives
the agent enough SeatLayer context to make a correct plan while requiring it to
adapt to the repository's existing architecture, checkout, tests, and UI.

> **Use the portable skill**
>
> Install the [SeatLayer AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit)
> to give Codex, Claude Code, GitHub Copilot, or another coding agent this
> workflow plus read-only diagnostics and verification guidance.

## Give the agent these sources

| Context | URL |
|---|---|
| Portable integration skill | `https://github.com/seatlayer/seatlayer-ai-toolkit/tree/main/skills/integrate-seatlayer` |
| Documentation index | `https://docs.seatlayer.io/llms.txt` |
| Full corpus when context allows | `https://docs.seatlayer.io/llms-full.txt` |
| First integration | `https://docs.seatlayer.io/start/quickstart/index.md` |
| Complete checkout | `https://docs.seatlayer.io/examples/complete-checkout/index.md` |
| Production practices | `https://docs.seatlayer.io/integrations/best-practices/index.md` |
| Exact SDK contract | `https://docs.seatlayer.io/buyer-sdk/seat-picker/index.md` |
| Exact booking contract | `https://docs.seatlayer.io/server-api/booking/index.md` |

Use one-page Markdown routes for focused work. Use the complete corpus for an
agent that must choose between multiple integration surfaces.

## Copyable agent instruction

```text title="SEATLAYER_AGENT.md"
Implement SeatLayer in this repository as a production integration.

Read:
- https://docs.seatlayer.io/llms.txt
- https://docs.seatlayer.io/start/choose-an-integration/index.md
- https://docs.seatlayer.io/integrations/best-practices/index.md
- https://docs.seatlayer.io/examples/complete-checkout/index.md

Repository-first rules:
1. Read the repository's agent instructions and contribution guidance.
2. Inspect package manager, framework, routing, environment configuration,
   server/client boundary, payment/order code, error conventions, and tests.
3. Do not replace existing architecture or styling with a demo application.
4. State the chosen SeatLayer surface and why before editing.
5. If a required business decision cannot be discovered, identify it clearly.

SeatLayer invariants:
- A chart is reusable geometry; an event has independent live inventory.
- The browser selects and holds. A trusted server inspects and books.
- SEATLAYER_SECRET_KEY is server-only.
- Browser prices and checkout handoff values are not trusted payment input.
- A chart-priced checkout uses fresh hold inspection line items.
- A host-priced checkout recomputes its own price book on the server and records
  the SeatLayer inspected amount separately.
- bookingRef is a stable host order id and is reused for retries.
- HTTP 409 is a normal inventory conflict path.
- A repeated successful booking can return booked: [].
- Payment success and SeatLayer booking must have an explicit recovery policy.

Implement:
- the smallest complete integration in the existing application;
- typed browser-to-server payloads;
- server-only SeatLayer request helpers;
- useful expired-hold and conflict UX;
- idempotent order/booking coordination;
- environment variable documentation;
- tests matching this repository's conventions.

Verify:
- typecheck, tests, lint, and production build;
- no secret appears in client output;
- mobile, keyboard, loading, empty, expired, and error states;
- test-mode select -> hold -> inspect -> book;
- duplicate retry and payment/booking compensation behavior.

Hand off:
- changed files;
- commands and results;
- assumptions and unresolved production configuration;
- manual end-to-end steps;
- any follow-up for webhooks, observability, or deployment.
```

Save this block in the host repository only when the project owner wants a
persistent agent instruction. Otherwise include it in the implementation task.

## Repository discovery checklist

Before changing code, the agent should locate:

- package manager and exact install command;
- frontend entry point and client-only lifecycle boundary;
- backend route/service pattern;
- authenticated user and tenant context;
- existing product/event/order identifiers;
- payment provider and order state machine;
- environment validation;
- HTTP client and error normalization;
- test fixtures and network mocking;
- analytics adapter;
- deployment platform and secret management.

> **Do not generate a parallel app**
>
> The goal is to integrate SeatLayer into the user's product. A standalone demo
> can look complete while bypassing their authentication, checkout, tenancy,
> observability, and design system.

## Choose the implementation surface

| Repository need | Agent should choose |
|---|---|
| Complete buyer flow and custom checkout | `SeatPicker` |
| Fully custom cart and selection controls | `SeatingChart` |
| Simple direct-booking page without payment handoff | Hosted iframe |
| Organizer chart editing inside a CMS | `EmbeddedDesigner` plus `dse_` session |
| Operator live-event board | `SeatManager` plus `mse_` session |
| Custom operator interface | `ManageApi` |
| Multi-tenant provisioning | Workspaces plus server API |

The agent must not choose the iframe for a paid checkout that needs a parent
handoff; the current iframe protocol covers resizing and fullscreen, not a
checkout message.

## Required architecture

```text title="agent-target-architecture.txt"
Browser
  SeatPicker / SeatingChart
  -> returns opaque holdId

Host backend
  authenticate buyer
  authorize event and cart
  inspect hold with SEATLAYER_SECRET_KEY
  calculate trusted charge
  create/update host order
  coordinate payment
  book with stable bookingRef

Webhook receiver
  verify raw-body signature
  deduplicate occurrenceId
  reconcile asynchronous facts
```

## Test matrix

| Case | Expected proof |
|---|---|
| Successful checkout | One payment/order and one booking reference |
| Hold expired before payment | No charge; buyer can reselect |
| Inventory conflict | No partial booking; useful recovery |
| Duplicate request | Same booking reference; no duplicate charge |
| Payment succeeds, booking conflicts | Explicit compensation/manual-recovery state |
| Payment fails | Hold may expire/release; no booking |
| Missing secret | Server startup or route fails safely |
| Test/live mismatch | Clear configuration error |
| Browser bundle scan | No secret-key value or server module |
| Mobile and keyboard | Picker and surrounding checkout stay operable |

## Evidence the agent should return

A strong handoff includes command output, not just “tests pass”; names the
files changed; distinguishes automated from manual checks; reports skipped
checks; and lists production values still needed without printing secrets.

For chart-authoring agents, use the separate
[Designer MCP workflow](/agents/designer-mcp). For product implementation,
continue with [Build with agents](/agents/overview).

Source: https://docs.seatlayer.io/agents/integrate-seatlayer/index.mdx