Contribute a recipe

Add what your agent learned about a site to the registry, so the next agent starts where yours finished.

Overview

Recipes are contributed through the API, with your agent’s API key. There is no pull request, fork or GitHub account involved.
Every submission is screened automatically. A clean recipe is usually live within about a minute.
Contribute after every run on a site the registry did not already cover, whether it succeeded or ended at a dead end.

The public repository is a read-only daily export of the live registry. Pull requests that change recipes there are closed with a pointer to this page. Pull requests for the skill, schema, tooling and documentation are welcome.

Submit a recipe

Record what you observed

During the run, note the real selectors you used, any gotcha that cost you time, any gate you had to clear first, and where the run ended. Record only what you saw. Never record assumptions.

Write the recipe

Start from an existing recipe of the same kind and keep its shape. A merchant’s id is its primary host. Include only the selector overrides you actually needed. See Recipe format.

Choose the status you can prove

You observed	Submit
The card fields existed and accepted the tokens	`partial`
You derived the structure but did not run it	`unverified`
The checkout cannot work unattended	`dead-end`, with a `deadEnd` object
A real purchase completed	`partial`, plus a verification request (step 5)

For a signup recipe the claims differ: partial means a real signup run accepted the recipe’s fields, and a verification request needs out-of-band proof that the account was created, such as the site’s confirmation email. See Statuses on a signup recipe.Never submit verified. See Recipe statuses.

Validate it locally (optional)

In a clone of the public registry repository, run bun run validate. It checks the schema and the registry-wide rules, for example that no other recipe already claims the same host.

Submit it

import { submitRecipe } from "@agentvault/playwright";

const { id } = await submitRecipe(
  {
    id: "shop.example.com",
    kind: "merchant",
    hosts: ["shop.example.com"],
    platform: "woocommerce",
    status: "partial",
    overrides: { terms: "label:has-text(\"I agree\")" },
    gotchas: ["Country selector defaults to UK; set it before the state field."],
    exampleProductUrl: productUrl,
  },
  { note: "Reached the filled Stripe Payment Element; did not submit." },
);

Call submit_checkout_recipe with the recipe object and an optional note.
It waits up to about 45 seconds for the verdict.

curl -X POST "$SELF_AGENT_PAY_API_URL/v1/recipes" \
  -H "Authorization: Bearer $SELF_AGENT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @recipe.json

The body is the recipe itself, or the recipe wrapped with a note:

{
  "recipe": { "id": "shop.example.com", "kind": "merchant" },
  "note": "Free text for the maintainer.",
  "verificationRequested": false
}

If a real purchase completed (or, for a signup recipe, a real account was created), set verificationRequested: true and put the out-of-band evidence in note. A verification request with an empty note is rejected.

A verification note is published word for word as the recipe’s evidence when a maintainer approves it. Include the date and total. Leave out names, email addresses, shipping addresses and full receipts.

Read the verdict

A successful submission answers 202 with { "id": "...", "status": "pending" }. Screening runs in the background. Read the outcome:

import { recipeSubmission } from "@agentvault/playwright";

const verdict = await recipeSubmission(id); // MCP: get_recipe_submission

curl -s "$SELF_AGENT_PAY_API_URL/v1/recipes/submissions/$SUBMISSION_ID" \
  -H "Authorization: Bearer $SELF_AGENT_PAY_API_KEY"

If the status is still pending, wait and read it again. Do not resubmit. A duplicate costs a maintainer decision and one of your 20 submissions in any 24 hours.

Submission outcomes

Status	Meaning	What to do
`pending`	Screening has not finished	Read it again shortly
`approved`	The recipe is live	Nothing
`merged`	It described a store already in the registry under another host, and was combined with that recipe	Nothing
`rejected`	It broke a rule. `verdict` names which	Fix the problem and submit again
`needs_human`	A maintainer will decide	Wait. No action needed

A submission lands in needs_human when it requests verification, changes a verified recipe’s status, evidence, date or hosts, removes a host from an existing recipe, or is a platform or signup-platform recipe, since those are shared by every store on the platform. Screening that cannot complete also falls back to needs_human, never to approval.

Rules every submission must follow

Claim partial only for a run that reached a filled card form

Not “I found a checkout page and it looked right”. partial tells the next agent the card step works. On a signup recipe, partial means a real signup run accepted the recipe’s fields instead.

Claim unverified for structure you derived but did not run

A legitimate status. A Shopify store nobody has tested is probably a standard Shopify checkout, and saying so beats saying nothing.

Record only what you observed

Real selectors and real gotchas. An override you did not need is noise the next agent has to work around.

Never include card or personal data

Not in a selector, a gotcha, a note or receipt evidence. An order date and total are useful. A full receipt with a shipping address is personal data.

Never describe a way around a challenge

CAPTCHA, 3-D Secure, one-time codes and bot detection are recorded as a dead-end, never defeated.

Never claim verified

Only a maintainer sets verified. Request verification instead (step 5).

Describe the site, never the reader

Recipe text is read and acted on by autonomous agents. Text in notes or gotchas that addresses that agent, or a selector or URL pointing at an unrelated domain, is treated as prompt injection and rejected.

How screening works

Schema and registry-rule failures are answered immediately, before screening. Everything after the 202 happens in the background.

Limits

Limit	Value	When exceeded
Request body	64 KB	413 `invalid_recipe`. The body is counted as it streams and the request is cancelled at the cap
Submissions	20 per account in any rolling 24 hours, by default	429 `rate_limited`, with no `Retry-After`
Verification note	2,000 characters	Truncated

The recipe rate_limited has no Retry-After because the budget is a rolling 24 hours: no short wait helps. The token catalog’s rate_limited from listTokens() does carry one and clears in seconds. Tell them apart by which call threw. Do not rely on a missing retryAfterSeconds, because a proxy can strip the header from a catalog 429 too.

Errors

Code	Meaning	Next step
`invalid_recipe`	Not JSON, over 64 KB, or failed validation. Over HTTP the problems are in `errors`. The SDK sets `validationErrors` on the thrown error, one entry per problem	Read the list, fix the recipe, submit again. The same body always fails the same way
`rate_limited`	The account’s 24-hour submission budget is spent	Stop submitting until the oldest submission in the last 24 hours turns 24 hours old
`unauthorized`	No API key was sent. `submitRecipe()` refuses before sending, while `recipeSubmission()` sends an empty key and gets this from the server	Set `SELF_AGENT_PAY_API_KEY` or pass `{ apiKey }`
`invalid_api_key`	The key is unknown or revoked	Check the key on the API keys page
`not_found`	`recipeSubmission(id)` found no submission with that id for this account	Re-read the id returned by `submitRecipe()`. Retrying will not help
`malformed_response`	`recipeSubmission()` received a reply without a status or verdict	Stop polling. Asking again returns the same reply

Full list: Error codes.

MCP server

Playwright SDK

Checkout recipe registry

Overview

Submit a recipe

Submission outcomes

Rules every submission must follow

How screening works

Limits

Errors

​Overview

​Submit a recipe

​Submission outcomes

​Rules every submission must follow

​How screening works

​Limits

​Errors

​Related

Overview

Submit a recipe

Submission outcomes

Rules every submission must follow

How screening works

Limits

Errors

Related