Merktop Wallet, pay (and get paid) for x402 resources

This skill lets you pay any x402-gated API, dataset, or service from a non-custodial Merktop wallet, and settle in USDC on Base. You never hold keys or funds: each payment is pulled just-in-time from the user's wallet through a spend permission they granted, and the on-chain spend cap is absolute, if a payment would exceed the budget, it fails instead of overspending.

When to use it

Use this when a task needs a resource that returns HTTP 402 Payment Required (paid APIs, agent-to-agent services, x402 data feeds, hosted paywalls). Do NOT use it for free endpoints.

Pay for a resource

Send the target x402 URL through the Merktop pay-proxy. It handles the whole 402 → pay → retry loop and streams the paid response back to you.

# GET an x402 resource
curl -s "https://facilitator.merktop.com/buyer/$MERKTOP_BUYER_KEY/pay?url=https://seller.example/api/data"

# POST with a body (the body + content-type are forwarded to the seller verbatim)
curl -s -X POST "https://facilitator.merktop.com/buyer/$MERKTOP_BUYER_KEY/pay?url=https://seller.example/api/run" \
  -H "content-type: application/json" \
  -d '{"prompt":"..."}'

The proxy returns the seller's response body (use it as the result). The response header x-merktop-spent-cents tells you exactly what the call cost, so you can report spend back to the user.

Security: you can also send the key as the x-merktop-key header to https://facilitator.merktop.com/api/buyer/pay?url=<resource> instead of in the path, so it never appears in URL or proxy logs. Both forms work.

Read the outcome

• 2xx → paid and delivered; the body is the seller's response (the upstream status is passed through verbatim, so 201/204/206 are also success). Check x-merktop-spent-cents for the cost.
• 402 spend_cap_exceeded → the budget for this period is used up. Stop; tell the user to raise it.
• 402 no_permission → the user hasn't activated their agent / set a budget yet (see Setup).
• 401 invalid_buyer_key → MERKTOP_BUYER_KEY is missing or wrong.
• 403 recipient_blocked / sender_blocked → a sanctioned party; never retry.
• 429 rate_limited → back off and retry after the retry-after seconds.
• 502 pay_failed → the seller or settlement failed; the pull (if any) is swept back to the user's wallet on a best-effort basis (in the rare case the sweep-back also fails, Merktop records it for reconciliation). The spend claim is released, so retrying is generally safe, but verify the balance before assuming a refund landed.

Get paid (sell a resource)

To EARN, gate your own endpoint behind a Merktop hosted paywall and let other agents pay you in USDC, settled to your wallet by Merktop's facilitator:

1. Create a paywall in the Merktop app (https://facilitator.merktop.com/docs), pick your price and the URL it protects.
2. Share the public link https://facilitator.merktop.com/p/<your-slug>. Any agent (including ones running this skill) can pay it; the USDC lands in your wallet.

Rules of good behavior

• Only pay for resources the current task genuinely needs. Prefer free sources first.
• Treat x-merktop-spent-cents as real money, report it; don't loop on paid calls.
• Never try to bypass or exceed the cap. It is enforced on-chain; attempts just fail.
• Setup (one time, by the user): get a buyer key + set a budget at https://facilitator.merktop.com/docs, then put it in MERKTOP_BUYER_KEY.