# skills.trade

> A marketplace for Agent Skills — SKILL.md bundles, human-reviewed before
> they go live, priced in dollars. Authors publish the procedures they
> already wrote; buyers get one free sandboxed run before paying.

Every listing is queued as `in_review` and only reaches the catalog once a
human reviewer approves it, so nothing here is auto-published spam. Every
price is set in dollars and stays fixed; how it settles depends on the path.
A human checkout settles on Solana in $SKILLS, struck at a live USD rate at
the moment of purchase. The path below settles differently: paying over x402
on the download route settles in USDC, straight off the dollar price, with no
token quote involved.

## Agent flow

1. Search or browse the catalog: `GET /api/skills`.
2. Read one listing in full, including pricing and how to trial or buy it:
   `GET /api/skills/{slug}`.
3. Run the free evaluation once per listing, streamed:
   `POST /api/skills/{slug}/trial`.
4. Pay for the listing you want to keep, over x402, on the download route:
   `GET /api/skills/{slug}/download`. An unpaid request gets back a 402
   with an x402 `PaymentRequirements` challenge; retry with an
   `X-PAYMENT` header carrying the base64-encoded payment payload.

Step 3 needs a session — sign in headlessly first, see "Sign-in" below. Step 4
does not: the x402 path is deliberately sessionless, with payment riding
entirely in the `X-PAYMENT` header. Stock x402 v2 client libraries work
unmodified: the 402 also carries the challenge base64-encoded in a
`PAYMENT-REQUIRED` response header, and `PAYMENT-SIGNATURE` is accepted
as an alias for `X-PAYMENT`.

## API endpoints

- `GET /api/skills` — search or list live listings. No params: the whole
  catalog. With `q`, `category`, `tag`, `limit` or `cursor`: filtered
  and paginated.
- `GET /api/skills/{slug}` — one listing: the record, USD pricing with an
  optional live token quote, how to trial it, how to buy it.
- `POST /api/skills/{slug}/trial` — the one free evaluation run, streamed as
  newline-delimited JSON. Requires a session.
- `GET /api/skills/{slug}/download?format=md|zip` — the purchased payload.
  402 with an x402 challenge if you have not paid. No session required — a
  session only matters if you already own the listing from a prior checkout;
  otherwise pay over x402 in the same request.
- `POST /api/auth/nonce` — issue a Sign-In-With-Solana challenge.
- `POST /api/auth/verify` — complete sign-in with a signed SIWS message;
  sets the session cookie.
- `GET /api/auth/session` — who is signed in, if anyone.
- `DELETE /api/auth/session` — sign out.
- `GET /api/token/quote` — the live $SKILLS/USD rate. Public, no session
  needed. 503 rather than a stale rate when the feed is down.

## Sign-in

Headless Sign-In-With-Solana, no browser or wallet extension required — a
keypair and an HTTP client are enough:

1. `POST /api/auth/nonce` — returns the SIWS fields to sign and sets an
   httpOnly nonce cookie. Send that cookie on the next request.
2. Build the SIWS message from the returned fields and sign it with your
   Solana keypair.
3. `POST /api/auth/verify` with `{ address, signedMessage, signature }`,
   the message bytes and signature both base64-encoded. On success, sets the
   session cookie used by the trial and download routes.

A worked example, including the exact message format, is in
`scripts/publish-seed-skills.mjs`.

## Full contract

`https://skillstrade.xyz/api/openapi.json` — OpenAPI 3.1, every request and response
shape above including the exact x402 challenge schema.

`https://skillstrade.xyz/agents` — this same flow, with curl-able examples.