# Make your x402 API discoverable on x402gle

> You are an AI coding agent. A merchant who owns an x402-paid API asked you
> to get it listed on the x402gle catalog so other agents can find and pay
> for it. This document is your instruction set. Follow it end to end.

x402gle does not list an API by reading its description. It **auditions** the
API: it discovers every paid route, makes a REAL paid call to each one,
AI-scores the live response, and synthesizes an agent-callable Skill from what
actually came back. A passing audition lists the API automatically.

Your job: run the audition, read the result, fix what scored low, re-audition
until every route passes.

## Step 1 — make the API discoverable

The audition discovers paid routes three ways, in this order of preference:

1. **OpenAPI document** (preferred) — serve OpenAPI 3.1 at `/openapi.json`.
   - `info.x-guidance`: a short note on what the API is for.
   - Each paid operation: a `requestBody` schema and an `x-payment-info`
     block with `protocols` (x402 and/or mpp) and a structured `price`.
2. **Well-known descriptor** — `/.well-known/x402` listing the paid routes.
3. **Bare probe** — a request to the URL that returns HTTP 402 with a valid
   payment manifest.

If none of these resolve, the audition returns `discovery_failed` and the
API cannot be tested. Expose the OpenAPI document — that is the fix.

## Step 2 — install the OpenDexter CLI

```bash
npx -y @dexterai/opendexter@latest --help
```

No global install needed; `npx` runs the latest published version.

## Step 3 — audition the API

Pass the merchant's server origin (audits every paid route on the server) or a
single endpoint URL (audits that route and discovers its siblings):

```bash
npx @dexterai/opendexter audition "<MERCHANT_SERVER_URL>" --json
```

Always use `--json` — it is the machine-readable path designed for you.

## Step 4 — read the result

The `--json` output is:

```
{
  "ok": true,
  "origin": "https://merchant-api.com",
  "summary": { "total": 3, "registered": 3, "failed": 0, "avgScore": 84 },
  "routes": [
    {
      "url": "https://merchant-api.com/price/eth",
      "score": 91,
      "status": "pass",
      "verdict": "<what an agent asked for and what came back>",
      "fixInstructions": null,
      "synthesizedSkill": { ...typed inputs/outputs, grounded in the real response... },
      "mcpTool": { ...ready-to-paste MCP tool definition... }
    }
  ]
}
```

For each route:
- `score` (0–100) and `status` (`pass` / `fail` / `inconclusive`) — the
  verdict from a real paid call, not a metadata guess.
- `verdict` — what the test agent sent and what came back.
- `fixInstructions` — concrete steps when a route scored low. `null` on pass.
- `synthesizedSkill` + `mcpTool` — the agent-callable Skill built from the
  live endpoint. This is what other agents will use to call the merchant.
- `shareUrl` — a public, shareable page for this route's result
  (`x402gle.com/audition/<id>`): the score, the verdict, the synthesized
  Skill. Worth surfacing to the merchant.

## Step 5 — fix and re-audition

For every route where `status` is not `pass`, apply `fixInstructions` to the
merchant's API (the OpenAPI document, the endpoint behaviour, or the price),
then re-run `audition`. Repeat until every route passes.

Note: the audition is rate-limited per origin (real money is spent on every
call). If a re-run returns HTTP 429 `cooldown_active`, wait until the
`cooldownUntil` timestamp and retry.

## Step 6 — confirm the listing

A passing audition lists the API in the catalog automatically. Once listed,
the synthesized Skill is served at:

- `https://x402gle.com/servers/{host}` — the public host page
- `https://x402gle.com/servers/{host}/SKILL.md` — Anthropic SKILL.md format
- `https://x402gle.com/servers/{host}/skills.json` — flat skill index
- `https://x402gle.com/servers/{host}/.well-known/agent.json` — A2A card

Substitute the merchant's hostname for `{host}`.

## The paste-prompt (for the merchant to give their agent)

If the API is already indexed on x402gle, the merchant's own server page —
`https://x402gle.com/servers/{host}` — carries a paste-prompt with the URL
already filled in and the weak routes named inline. Otherwise, paste this
generic prompt verbatim into Cursor, Claude Code, or Codex:

> Make my x402 API discoverable on x402gle. Read the instructions at
> https://x402gle.com/agent.md and follow them end to end. Install the
> OpenDexter CLI, run `npx @dexterai/opendexter audition <my-server-url> --json`,
> read the score and fixInstructions for every route, fix my OpenAPI and
> endpoints until each route passes, and re-audition until it does. A passing
> audition lists my API automatically.

## What this is not

This is not a schema linter. The audition spends real USDC calling the API
and grades the response an agent actually receives. A route that returns a
broken or empty payload scores low no matter how clean its OpenAPI document
is. The catalog only lists what works.

## Reference

- Human-facing version of this page: https://x402gle.com/agent
- CLI package: `@dexterai/opendexter` on npm
- The x402 protocol: https://www.x402.org/
- Contact: branch@dexter.cash