> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up a recipe

> Ask the registry what is already known about a site before your agent touches the cart.

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

<Tabs>
  <Tab title="SDK">
    ```ts theme={null}
    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.
  </Tab>

  <Tab title="MCP">
    Call `get_checkout_recipes` with the page URL. It needs no open page and no
    authentication.
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

<Warning>
  **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.
</Warning>

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 |

<Note>
  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**](/dashboard/logins#pre-approved-signups) list. See [Agent signup](/guides/agent-signup).
</Note>

## Choose a store

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

```ts theme={null}
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.

## Other reads

<Tabs>
  <Tab title="Index">
    ```bash theme={null}
    curl -s "$SELF_AGENT_PAY_API_URL/v1/recipes"
    ```

    Returns `{ "recipes": [...] }` with `key`, `kind`, `status` and
    `registryVersion` per recipe, plus `platform` on merchant and signup recipes
    only. Public, cached for five minutes. See the
    [HTTP API](/reference/http-api) for the full entry shape.
  </Tab>

  <Tab title="Every recipe body">
    ```bash theme={null}
    curl -s "$SELF_AGENT_PAY_API_URL/v1/recipes?full=1"
    ```

    The index with each recipe's full body under `recipe`. This is what the daily
    public export uses.
  </Tab>
</Tabs>

## 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](/registry/contribute).

## Related

* [Recipe format](/registry/recipe-format)
* [Recipe statuses](/registry/statuses)
* [HTTP API](/reference/http-api)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.