# REST API

> The same functions as the MCP tools over plain HTTP, every route with the tool it matches.

The base URL is `https://api.402lounge.com/v1`. Bodies are JSON objects, answers are JSON. Each route does what its tool does, with the same fields, so the [MCP tools](https://402lounge.com/docs/tools.md) describe the inputs.

## Proving who you are

Send `Authorization: Bearer lg_...` with a session token, or the `SIGN-IN-WITH-X` header of an x402 client. A body may also carry `session_token` or `proof: {message, signature}`. Without any of them a route that needs an account answers `auth_required` with a challenge. [Accounts and sign-in](https://402lounge.com/docs/accounts.md) explains each way.

`X-Client` names your client, like `claude-code 2.1`. It shows up in the agent's list of apps.

`X-Company-Id` names the company a call of a person is for, when their login is in several companies. Without it the API takes the company used last. Agents never need it, see [one login, many companies](https://402lounge.com/docs/accounts.md#one-login-many-companies).

Errors look the same as over MCP, with the HTTP status of [Errors and limits](https://402lounge.com/docs/errors.md). Browsers may only call the API from 402lounge.com and app.402lounge.com.

## Start and account

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/requirements` | `lounge.requirements` | Rules, prices, the current terms and the sentences you sign. No account |
| `GET /v1/terms` | `lounge.terms` | The current terms and privacy notice. No account |
| `POST /v1/signup` | `lounge.signup` | Create the account. Answers 402 with the challenge and, once open, a 0.001 USDC option |
| `POST /v1/session` | `lounge.session` | A new session token, by signature or by 0.001 USDC |
| `GET /v1/me` | `lounge.me` | You, your company and its wallets. For a person also `memberships` and `company_selected`. For a login of the app without a company, who you are and how to create one |
| `PATCH /v1/me` | `lounge.agent.update` | Your name inside the company |
| `GET /v1/apps` | `lounge.apps` | The clients you have used |
| `POST /v1/apps/{client}/{action}` | `lounge.apps` | `deactivate`, `activate` or `disconnect` a client |
| `GET /v1/notices` | `lounge.notices` | Your notices. `?all=1` includes the read ones |
| `POST /v1/notices/{id}/ack` | `lounge.notices` | Mark a notice as read |
| `POST /v1/dashboard-link` | `lounge.dashboard.link` | A one-time dashboard link for ten minutes |
| `GET /v1/me/export` | `lounge.account.export` | Everything we keep about the agent, as a JSON file |
| `POST /v1/me/delete` | `lounge.account.delete` | Schedule the deletion in 7 days, with a fresh signature |
| `DELETE /v1/me/delete` | `lounge.account.delete` | Cancel the deletion |

## Wallets

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/wallets` | `lounge.wallet.list` | All wallets of the company. `?mine=1` for your own |
| `POST /v1/wallets` | `lounge.wallet.add` | Add a wallet. It signs `wallet_proof` or pays 0.001 USDC. The owner adds one in the app by its signature, with `agent_id` or `null` for none |
| `PATCH /v1/wallets/{address}` | `company.wallet.label` | Name a wallet, `label: null` clears it |
| `DELETE /v1/wallets/{address}` | `lounge.wallet.remove` | Remove a wallet, its receipts stay |
| `POST /v1/wallets/{address}/primary` | `lounge.wallet.primary` | The wallet you sign in with |
| `POST /v1/wallets/{address}/assign` | `company.wallet.assign` | Move a wallet to another agent, `agent_id: null` unassigns it |

## Receipts and the register

| Route | Tool | What it does |
|---|---|---|
| `POST /v1/receipts` | `receipts.record` | Report a payment you made |
| `GET /v1/receipts` | `receipts.list` | One month of receipts. `?month=2026-10&status=&agent_id=&wallet=&mine=1&limit=&before=`, `recent=1` for the newest of any month |
| `GET /v1/receipts/{id}` | `receipts.get` | One receipt by id or transaction hash |
| `GET /v1/wallet-names` | | Your company's names for wallets outside the register |
| `PUT /v1/wallet-names/{address}` | | Name a wallet you paid that no listing claims, `{name}`, 1 to 60 characters. Shows on your receipts as `seller.your_name` |
| `DELETE /v1/wallet-names/{address}` | | Forget that name |
| `GET /v1/register/{address}` | `register.lookup` | Who is behind a payTo wallet. No account |

## Directory and listings

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/listings` | `directory.search` | The directory. `?q=&filter=all|verified|mcp&sort=level|new|name&limit=&offset=`. A booked sponsored place comes in `sponsored`. No account, cached for a minute |
| `GET /v1/listings/{slug}` | `directory.get` | One listing with its wallets, calls and prices, other networks and links. No account |
| `POST /v1/listings/preview` | `directory.preview` | Read the 402 answer of one paid URL and show the listing it would make. Body `{url}` |
| `POST /v1/listings` | `directory.submit` | List the service on level 0 under your company. Body `{url, contact_email}`. Admins and owners |
| `POST /v1/listings/{slug}/claim` | `directory.claim` | A wallet of the listing signs, the listing belongs to your company on level 1. Body `{address, wallet_proof?}`. Admins and owners |

## Plans and billing

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/billing` | `billing.get` | Plan, period, end, status, limits, this month's usage, the one-time 20 %, `archive`, `retention` and `pay_with` |
| `POST /v1/billing/checkout` | `billing.checkout` | A Polar checkout for `{plan: "books"|"teams", period: "month"|"year"}` or for the archive, `{archive: "month"|"year"}`. Admins, owners and finance |
| `POST /v1/billing/portal` | `billing.portal` | Polar's customer portal: payment method, invoices, change or cancel. Admins, owners and finance |
| `GET /v1/sponsor` | `sponsor.get` | Your sponsored places and whether the place is free |
| `GET /v1/sponsor/ad` | | `?listing=`: the text of the listing's sponsored tile, or what it says without one, and the rules |
| `PUT /v1/sponsor/ad` | | `{listing, title, body, url}`: the title keeps the listing's name, the text up to 140 characters, the link on the listing's domain or a subdomain. Changeable while the place runs |
| `POST /v1/sponsor/checkout` | `sponsor.checkout` | A Polar checkout for one month of the sponsored place, `{listing}`, paid once. Admins and owners of the company the listing belongs to |
| `POST /v1/billing/usdc/quote` | `billing.quote` | An offer to pay in USDC: `{plan, period}`, `{archive}`, `{sponsor}` or `{seller_check}`. Price in EUR with VAT, the amount in USDC, `pay_to` and `pay_url`, open for 30 minutes. Admins, owners and finance ([Paying 402lounge](https://402lounge.com/docs/billing.md)) |
| `GET /v1/billing/usdc/quotes` | No tool | The company's last 50 offers with their status |
| `GET /v1/billing/usdc/quote/{id}` | `billing.quote` | One offer: `open`, `paid` or `expired`, with the transaction and the invoice once paid |
| `POST /v1/billing/usdc/pay/{id}` | No tool | The offer's x402 route. Without payment 402 with the amount, with `PAYMENT-SIGNATURE` paid, answers with the invoice. No account |
| `GET /v1/billing/invoices` | `billing.invoices` | The invoices of 402lounge for payments in USDC, newest first |
| `GET /v1/billing/invoices/{id}` | `billing.invoices` | One invoice with its full content |
| `GET /v1/billing/invoices/{id}/pdf` | No tool | The invoice as PDF, `?lang=de` for German, from the archive |
| `POST /v1/webhooks/polar` | No tool | Polar's events, signed after Standard Webhooks. Only for Polar |

## Company and people

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/company` | `company.get` | Data, level, what is missing, agents and people |
| `PATCH /v1/company` | `company.update` | Fill in or change the company data, also `currency`, `skr` and `own_accounts` |
| `GET /v1/countries` | | What a company states about its taxes, per country: name, format and example of the VAT number, the tax or register number, the small business scheme with its threshold, the statuses that fit. Every EU state and the USA, `general` for the rest. Public |
| `GET /v1/currencies` | | The currencies a company can see its amounts in: EUR, USD and every currency with an ECB reference rate. Public |
| `POST /v1/company/vat-check` | `company.vat_check` | Ask VIES again |
| `POST /v1/company/email` | `company.email` | Set the email and mail a code |
| `POST /v1/company/email/confirm` | `company.email` | Confirm the code |
| `DELETE /v1/company/email` | `company.email` | Remove the email, only without company data |
| `PUT /v1/company/logo` | | The logo as the request body: PNG, JPEG or WebP, up to 256 KB. PNG and JPEG also go onto the documents the company issues from then on. Owner or admin agent |
| `DELETE /v1/company/logo` | | Remove the logo |
| `GET /v1/logos/{company}/{file}` | | The logo file, public. `company.logo` in `GET /v1/company` is its path |
| `GET /v1/company/agents` | `company.agents` | The agents with their wallets and this month's spending |
| `PATCH /v1/company/agents/{id}` | `company.agent.update` | Rename an agent or change its role |
| `DELETE /v1/company/agents/{id}` | `company.agent.remove` | Remove an agent in 7 days |
| `GET /v1/company/sessions` | | The open session tokens of every agent: client, wallet, since, until |
| `DELETE /v1/company/agents/{id}/sessions` | | End all session tokens of an agent. The agent itself, the owner or an admin agent |
| `DELETE /v1/company/agents/{id}/sessions/{sid}` | | End one of them |
| `POST /v1/company/invite` | `company.invite` | An invite code for seven days |
| `POST /v1/company/join` | `company.join` | Join a company with a code |
| `GET /v1/company/members` | `company.members` | The people in the company |
| `POST /v1/company/members` | `company.members` | Invite a person with a role |
| `PATCH /v1/company/members/{id}` | `company.members` | Change a person's role |
| `DELETE /v1/company/members/{id}` | `company.members` | Take a person out |
| `GET /v1/company/roles` | | The company's own roles, the fixed ones and the areas |
| `POST /v1/company/roles` | | `{name, areas}`: a role with none, read or write per area (receipts also export). Owner or admin agent |
| `PATCH /v1/company/roles/{id}` | | Rename it or change its areas |
| `DELETE /v1/company/roles/{id}` | | Delete a role nobody has |
| `GET /v1/company/export` | No tool | The company's books as one ZIP: every document as JSON and PDF, `receipts.csv`, `documents.csv`. Owner, admin, finance and adviser |
| `POST /v1/company/close` | `company.close` | Close the company in 30 days. Body `{name}` with the company name. With `now: true, export_kept: true` it closes at once and deletes receipts and documents. Owner and admin |
| `DELETE /v1/company/close` | `company.close` | Cancel the closing. Owner and admin |

## Board

Requests between the people and agents of a company, for example the tax adviser asking for a missing receipt. Whoever reads the receipts reads and writes here.

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/requests` | `company.requests` | The requests, last active first. `?status=open` (default), `done` or `all`, plus `open`, the number still open |
| `POST /v1/requests` | `company.requests` | `{title, body?, month?, receipt_id?}`: ask something. Mails the company email and everybody who exports or changes receipts |
| `GET /v1/requests/{id}` | `company.requests` | One request with its answers |
| `POST /v1/requests/{id}/replies` | `company.requests` | `{body}`: answer. Opens a done request again and mails everybody in the thread |
| `PATCH /v1/requests/{id}` | `company.requests` | `{status: "done"}` or `"open"` |
| `DELETE /v1/requests/{id}` | `company.requests` | Take it back. Who asked, the owner or an admin agent |

## Documents

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/invoices` | `invoices.list` | The documents, newest first. `?month=2026-10&limit=` |
| `POST /v1/invoices/issue` | `invoices.issue` | Issue the documents for a finished month. Owner, admin and finance |
| `GET /v1/invoices/draft` | `invoices.draft` | The month so far as drafts, one per seller. `?month=2026-11` |
| `GET /v1/invoices/draft/pdf` | No tool | A draft as PDF. `?month=&seller=&lang=de` |
| `POST /v1/invoices/{id}/cancel` | `invoices.cancel` | Cancel a document. Body `{reason}`. Owner, admin and finance |
| `GET /v1/invoices/export` | No tool | A finished month for the books: `?month=2026-10&format=csv` (one line per document line) or `format=datev` (DATEV Buchungsstapel). From Books on. Owner, admin, finance and adviser. [Monthly documents](https://402lounge.com/docs/vouchers.md#export-for-the-books) |
| `GET /v1/invoices/{id}` | `invoices.get` | One document as JSON |
| `GET /v1/invoices/{id}/pdf` | No tool | The archived PDF, English or `?lang=de`, byte for byte as issued |
| `GET /v1/invoices/{id}/xml` | No tool | The e-invoice of an invoice or credit note (EN 16931, UN/CEFACT CII), as archived. Vouchers have none |

## Sellers

| Route | Tool | What it does |
|---|---|---|
| `GET /v1/seller` | `seller.get` | Your listings with their level, the company check, the seller profile, the mandate and self-billing |
| `PATCH /v1/seller/profile` | `seller.profile` | The person who acts for the company (`representative_name`, required for level 2), register court and number (optional, or `no_register`), `sole_proprietor`, `show_name`. Admins and owners |
| `POST /v1/seller/checks` | `seller.check` | Start the company check of a listing on level 1. Body `{listing}`. Admins and owners |
| `GET /v1/seller/checks/{id}` | `seller.check` | The check with its steps, the domain email and the DNS record as the other way |
| `POST /v1/seller/checks/{id}/email` | `seller.check` | Send a code to `{email}` at the domain of the listing. Admins and owners |
| `POST /v1/seller/checks/{id}/email/confirm` | `seller.check` | Confirm it with `{code}`, then the steps run again. Admins and owners |
| `POST /v1/seller/checks/{id}/verify` | `seller.check` | Run the steps again. Admins and owners |
| `POST /v1/seller/checks/{id}/checkout` | `seller.check` | A Polar checkout for one year of the check (10 €). Admins, owners and finance |
| `DELETE /v1/seller/checks/{id}` | `seller.check` | Withdraw a check that is open or in review |
| `GET /v1/seller/mandate` | `seller.mandate` | The invoicing mandate: text, version, sha256, statement, whether it is signed |
| `POST /v1/seller/mandate` | `seller.mandate` | Sign it. An admin agent: first the challenge, then `{agreement_proof}`. An owner in the app: `{confirm: true}` |
| `DELETE /v1/seller/mandate` | `seller.mandate` | Revoke it, in force until the end of the month |
| `GET /v1/seller/self-billing` | `seller.self_billing` | The self-billing agreement and whether it is signed |
| `POST /v1/seller/self-billing` | `seller.self_billing` | Agree to it, as the mandate |
| `DELETE /v1/seller/self-billing` | `seller.self_billing` | End it, in force until the end of the month |
| `GET /v1/seller/invoices` | `seller.invoices` | Invoices in your name, credit notes you received and their cancellations. `?month=&limit=` |
| `GET /v1/seller/invoices/{id}` | `seller.invoices` | One of them as JSON |
| `GET /v1/seller/invoices/{id}/pdf` | No tool | Its PDF, English or `?lang=de` |
| `GET /v1/seller/invoices/{id}/xml` | No tool | Its e-invoice |
| `POST /v1/seller/invoices/{id}/cancel` | `seller.invoices.cancel` | Cancel it with `{reason}`. Admins, owners and finance |

## For agents that read first

| Route | What it is |
|---|---|
| `GET /llms.txt` | Short instructions for agents on the API host |
| `GET /skill.md` | Sign-up and the first receipt as a skill file |
| `GET /.well-known/x402` | What is free and what costs 0.001 USDC, for x402 clients |
| `GET /health` | Whether the API is up |

## Used by the website

The website and the app call these. They are public, but not meant for agents.

| Route | What it does |
|---|---|
| `POST /v1/auth/web3/challenge` | A sign-in challenge for the dashboard |
| `POST /v1/auth/web3/verify` | Sign in to the dashboard with a wallet signature |
| `POST /v1/auth/email/link` | An email link into the app. For an address without a company it starts the sign-up |
| `POST /v1/companies` | A signed-in person creates a company and becomes its owner, also next to the companies they are in already. Body: the fields of `PATCH /v1/company`, `name` required, and `accept: {terms, privacy, business: true}` |
| `POST /v1/help` | The Help button of the app: a signed-in person writes what went wrong, also before the company exists. Body: `message` (3 to 4000 characters), `page`, `context: {last_error, locale, screen}`. We answer by mail to the sign-in address. 20 a day per login |
| `POST /v1/me/terms` | Accept the current terms in the app, `{accept: true}`, with `all: true` for every company of the person. For people, and for an agent signed in with its dashboard link |
| `POST /v1/auth/sso` | Whether a work address `{email}` signs in with SSO. Answers `sso_not_available` (501) while SSO is off |
| `POST /v1/reports` | Report a listing or an agent for illegal content or a breach of the terms |
| `POST /v1/track` | Count a view or a click on a listing page, without cookies |
| `GET /v1/stats` | Calls and lookups of the last days, as counts only |
| `GET /v1/status` | Each part of the service (`indexer`, `fx`, `documents`, `api`) as `ok`, `degraded` or `down`, with the incidents of the last 30 days. A minute old at most |
| `GET /v1/blog` | Published articles |
| `GET /v1/blog/{slug}` | One article |
| `GET /v1/changelog` | Published changelog entries |