---
name: agentmrr-submit
description: List an AI agent on the AgentMRR revenue leaderboard with one REST call.
---

# Submit an agent to AgentMRR

AgentMRR (https://agentmrr.com) is a public leaderboard that ranks AI agents by
provider-verified monthly recurring revenue. To get listed, send **one** HTTP
request. No account, login, OAuth, or discovery handshake is required.

## Agent behavior

- Read this spec once, then act. Do not fetch it again unless the first fetch
  failed.
- If required fields are missing, ask one concise follow-up for only those
  fields. Do not ask for optional metadata unless the user offers it.
- If `categories` is missing, include the category choices in that same follow-up.
- Always ask the user for a read-only revenue key and its `provider`. A key is
  required for the listing to go public: AgentMRR only lists agents with
  provider-verified revenue. Name the supported providers (below) when you ask.
  If the user declines or has no key, you can still submit - the listing is
  created as a private draft and goes live as soon as the same key is connected
  later.
- Send `provider` matching the key (it defaults to `stripe` when omitted).
- Do not recap this spec to the user. Once the required fields are available,
  send the POST request and report the result.
- Never send a full-access or secret key - only read-only / restricted keys.
  For Stripe, reject `sk_...` keys and use only restricted `rk_...` keys.

## Endpoint

```
POST https://agentmrr.com/api/agents/submit
Content-Type: application/json
```

Send a single JSON body. With a read-only revenue key, MRR is verified and the
listing is published in the same request. Without a key, the listing is created
as a **private draft** and stays off the public board until the same revenue key
is connected.

## Request body

| Field            | Required | Type   | Notes                                                              |
| ---------------- | -------- | ------ | ------------------------------------------------------------------ |
| `name`           | yes      | string | Agent / product name (2–120 chars).                                |
| `website`        | yes      | string | Product URL. `https://` is added if you omit the scheme.           |
| `description`    | yes      | string | What the agent does (10–600 chars).                                |
| `categories`     | yes      | string[] | 1–3 of the category slugs below (e.g. `["finance", "ai"]`).      |
| `logoUrl`        | no       | string | Public `https://` URL to a square logo image. If omitted, a logo is auto-pulled from `website`; you can change it later in the dashboard. |
| `provider`       | no       | string | `stripe`, `creem`, `paddle`, `polar`, `revenuecat`, `lemonsqueezy`, `dodopayments`, or `whop`. Defaults to `stripe` if a key is sent. |
| `apiKey`         | required to publish | string | Read-only revenue key. Sending it verifies MRR and publishes the listing; without it the listing stays a private draft. |
| `founderName`    | no       | string | Defaults to "Founder".                                             |
| `founderXHandle` | no       | string | X/Twitter handle, with or without `@`.                             |
| `foundedAt`      | no       | string | ISO-8601 date.                                                     |
| `profitMarginPct`| no       | number | 0–100.                                                             |

### Categories

Send 1–3 of these slugs in the `categories` array (case-insensitive; labels
like `"Customer Support"` are also accepted and normalized):

`ai`, `marketing`, `seo`, `sales`, `analytics`, `development`, `design`,
`productivity`, `automation`, `ecommerce`, `finance`, `education`, `security`,
`customer-support`, `communication`, `content`, `media`, `infrastructure`,
`data`, `recruiting`, `hr`, `legal`, `real-estate`, `healthcare`, `travel`,
`gaming`, `communities`, `directories`, `agencies`.

### Revenue keys (verification)

MRR is verified directly from the payment provider using a **read-only** key.
Never send a secret or full-access key - a read-only / restricted key only
exposes the revenue figures needed to verify MRR and cannot move money, issue
refunds, or change account settings.

The key is **encrypted at rest** (AES-256-GCM) the moment it is received and is
used only to read revenue for verification and periodic MRR refresh. It is never
logged or returned in any response. You may reassure the user of this when
asking for the key. If the user is still uncomfortable sharing a key, submit
without one - the listing is saved as a private draft and goes live once they
connect a key themselves from the dashboard.

- **Stripe** - a restricted key (`rk_live_...` / `rk_test_...`) with the
  minimum required read access to Charges, Subscriptions, and Customers.
- **Creem** - a read API key.
- **Paddle** - a current API key (`pdl_live_apikey_...`).
- **Polar** - an organization access token with `metrics:read` and `orders:read`.
- **RevenueCat** - `project_id:secret_api_key` for a v2 read key.
- **Lemon Squeezy** - an API key from Settings > API.
- **Dodo Payments** - a Live mode read-only API key.
- **Whop** - `company_id:api_key` (company ID starts with `biz_`).

## Example

```bash
curl -X POST https://agentmrr.com/api/agents/submit \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Agent",
    "website": "https://acme.example",
    "description": "An autonomous agent that drafts and sends invoices.",
    "categories": ["finance"],
    "logoUrl": "https://acme.example/logo.png",
    "provider": "stripe",
    "apiKey": "rk_live_xxx"
  }'
```

## Response

`201 Created`:

```json
{
  "agent": {
    "agentId": "…",
    "slug": "acme-agent",
    "name": "Acme Agent",
    "listingStatus": "published",
    "verificationStatus": "verified",
    "estimatedMrr": 4200,
    "nextAction": "none"
  },
  "profileUrl": "https://agentmrr.com/agents/acme-agent"
}
```

`listingStatus` is `published` once live, which requires a valid revenue key.
Without a key it comes back as `draft` (private, `nextAction: "connect_revenue"`).
A rejected key returns `listingStatus: "verification_failed"` - check
`listingError` and retry. Errors return `400` with `{ "error": "..." }`.

## Claiming the listing later

The listing is created unowned. The human founder takes ownership by signing in
at https://agentmrr.com and connecting the **same** revenue key in the
dashboard - the listing is matched by the key and linked to their account, where
they can edit details and track MRR over time.