---
name: diet-mercator
description: Use Diet Mercator to run reliable paid APIs (search, scraping, image, audio and video generation, LLMs) and pay with Link over MPP, without signing in to Mercator.
---

# Diet Mercator

Diet Mercator is a curated directory of reliability-tested paid APIs. Any Link client that can pay a Stripe MPP challenge with a shared payment token (SPT) can use it. These are recommendations, not requirements: use what fits your client.

## Before the first job

- **Reuse the Link connection you already have.** If you can already create Link spend requests or shared payment tokens, use that connection. Avoid asking the user to approve a new Link connection just for Diet.
- **Prefer Link Balance.** Diet jobs usually cost cents. Balance pays small amounts reliably; card-backed spend requests are often rejected under $0.50. If the user has several payment methods, choose Balance (for link-cli, pass `--payment-method-id` with the Balance method from `link-cli payment-methods list`).
- **Keep approvals to one per job, or none.** If the user has a Balance auto-approve limit, stay within it. Otherwise ask once for the exact quoted total.
- **No Mercator sign-in is needed.** The REST API below works without OAuth.

## Run a job

1. Search: `GET https://mercator.sh/diet/v1/services/search?query=<what you need>`
2. Inspect: `GET https://mercator.sh/diet/v1/services/<serviceId>` for the exact input schema.
3. Quote: `POST https://mercator.sh/diet/v1/quote`

   ```json
   {"plan":{"nodes":[{"id":"image","serviceId":"<serviceId>","method":"POST","path":"<path>","input":{},"dependsOn":[]}]}}
   ```

4. Submit and pay. Build the body from the quote, with a fresh UUID as the idempotency key:

   ```bash
   PLAN='{"nodes":[{"id":"image","serviceId":"<serviceId>","method":"POST","path":"<path>","input":{},"dependsOn":[]}]}'
   BODY=$(jq -nc --argjson plan "$PLAN" --arg token "<quoteToken>" --arg total "<totalAmount>" \
     --arg key "$(uuidgen)" '{plan:$plan,quote_token:$token,approved_total:$total,idempotency_key:$key}')
   ```

   With link-cli, one command pays the `402` challenge and retries:

   ```bash
   link-cli mpp pay https://mercator.sh/diet/v1/jobs --method POST --data "$BODY" \
     --payment-method-id "$LINK_BALANCE_ID" \
     --context "Diet Mercator job for the user: <what it does and why>. Quoted at <totalAmount> USD for one run through mercator.sh, paid from Link Balance."
   ```

   `--context` must be at least 100 characters; describe the task so the user can recognize it when approving.

   Other clients: `POST` the body, take the Stripe challenge from `WWW-Authenticate`, get a shared payment token (SPT) for that amount from Link, and retry the identical request with `Authorization: Payment <credential>`.

5. Poll: `GET https://mercator.sh/diet/v1/jobs/<jobId>` until `status` is `succeeded`, `partially_succeeded` or `failed`.

## Recovering

- After an uncertain result (a timeout or `503`), retry the same body and payment: it returns the same job and never charges twice.
- If Stripe definitively rejects the payment (for example a declined card or invalid token), nothing was charged and no job exists. Get a fresh SPT, preferably from Link Balance, and retry the same body with it.
- A `409` has three meanings; read its message:
  - "Reuse the original payment token and purchase key": an earlier payment for this key may already have reached Stripe. Retry the same body with the original SPT. Never start a new purchase for the same task.
  - "This idempotency key belongs to a different purchase": the body changed. Resend the original body, or requote and use a new key for a genuinely new task.
  - "This quote expired before payment": nothing was charged. Requote and use a new key.
- Unused capacity is refunded to the original payment automatically.

## Alternatives

- **MCP with OAuth** at `https://mercator.sh/diet/mcp` adds MCP tools and job history per connection. Payment still comes from your Link client.
- **REST with OAuth:** send the bearer in `Authorization` and the MPP credential in `X-Mercator-Payment`.