Look up a recipe

Check the registry for any URL from the SDK, the MCP server or plain HTTP, and act on what comes back.

Why look up first

The most common reason an agent checkout fails is not a broken selector. It is landing on a store that never accepts a card. One lookup costs a single request and can save an entire run.

Look up a page

SDK
MCP
HTTP

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

const { merchant, platform } = await recipesForUrl(productUrl);

if (merchant?.deadEnd) {
  return { status: "DEAD_END", reason: merchant.deadEnd.type, details: merchant.deadEnd.details };
}

// merchant?.overrides: selector overrides to apply on top of platform.selectors

recipesForUrl() strips the URL to a safe fingerprint for you. Pass the absolute URL you navigated to, with its scheme: SdkPage has no url() getter. A relative or malformed string does not parse, so it is sent as is.

Call get_checkout_recipes with the page URL. It needs no open page and no authentication.

curl -sG "$SELF_AGENT_PAY_API_URL/v1/recipes" \
  --data-urlencode "url=https://shop.example.com/product/thing"

No Authorization header is needed. Strip the URL first, as described below.

Send only the scheme, host and path. Never the raw page URL.The lookup is unauthenticated, so its URL can reach logs. A hosted checkout URL often carries a session token, for example a Stripe cs_... path or a Shopify /checkouts/... path.Strip the query string, the fragment and any hosted-checkout token before you send it. recipesForUrl() does this for you when the URL is absolute, and the SDK exports the same logic as fingerprintUrl(). A string that does not parse as a URL, such as one without https://, is returned unchanged and sent whole.

A per-URL lookup is answered with Cache-Control: no-store, so a token that slips through is not kept in a shared cache.

Read the result

A lookup returns four slots. Each is a recipe or null.

Slot	Contains
`merchant`	The merchant recipe for this host
`platform`	The platform recipe the merchant names, or the one detected for the page
`signup`	The signup recipe for this host
`signupPlatform`	The signup platform recipe the signup names

All four are null when nobody has recorded coverage for the host yet. A missing field inside a recipe means nobody recorded it, not that it does not apply. Work through the checkout recipe in this order:

Field	What to do with it
`merchant.deadEnd`	Stop. Report the type and the details
`merchant.preconditions`	Clear each gate first. For example, `delivery_location` means fill a postcode from the address tokens before the buy button appears
`merchant.status`	Decide how much to trust the rest
`platform.detect`	Confirm the fingerprint still matches the page
`platform.steps`	Follow one instruction per phase
`merchant.overrides`	Apply on top of `platform.selectors`
`platform.cardSurface`, `platform.cvvTarget`	Find where the card goes. A merchant value overrides the platform’s

A signup recipe describes a form. It is not permission to create an account. Opening an account still goes through a signup request the account holder approves, one at a time or in advance through their Pre-approved signups list. See Agent signup.

Choose a store

When the user names a product but not a store, let the registry choose.

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

const candidates = await buyableMerchants();
// verified first, then partial, then unverified.
// Known dead ends are already excluded.

const shopifyOnly = await buyableMerchants({ platform: "shopify" });

buyableMerchants() returns index entries (key, kind, platform, status). platform is typed optional because the index omits it on platform recipes. A merchant entry carries it. Call recipesForUrl() once you have a product URL to get the full recipe. Choosing a known store is the single biggest factor in whether a purchase completes. Fall back to an arbitrary search result only when the registry has nothing suitable, and expect to report a dead end honestly if you hit one.

Errors

recipesForUrl() and buyableMerchants() throw without a code. A non-2xx response reports its HTTP status in the error message, and an unreachable registry reports that it could not connect. Branch on which call threw, not on a code. recipesForUrl() accepts { signal } so you can bound the request with an AbortSignal.

After the run

Contribute what you learned, whether the checkout succeeded or ended at a dead end. See Contribute a recipe.

MCP server

Playwright SDK

Checkout recipe registry

Why look up first

Look up a page

Read the result

Choose a store

Other reads

Errors

After the run

​Why look up first

​Look up a page

​Read the result

​Choose a store

​Other reads

​Errors

​After the run

​Related

Why look up first

Look up a page

Read the result

Choose a store

Other reads

Errors

After the run

Related