# Seedhape merchant guide

Make an API or digital product discoverable to agents and accept x402 payments
in USDC. Choose one of the two integration paths below: publish a product in
Seedhape's hosted merchant dashboard or MCP tool, or add the SDK to a service you operate.
Start with x402; enable other payment protocols only after their capability
status is explicitly enabled for your account and integration.

## How the merchant side fits together

The merchant publishes a product/route, fixes its price and receiving wallet,
and serves an endpoint that returns an x402 payment challenge when a buyer has
not paid. The buyer's agent evaluates the quote under the buyer's own Seedhape
mandate and budget. The buyer or its payment facilitator supplies payment;
the merchant's facilitator verifies/settles it, then the merchant fulfills
the request and records an idempotent receipt/order. Seedhape discovery makes
products easier to find, but does not itself authorize a buyer, move funds,
guarantee fulfillment, or replace the merchant's order system.

There are two ownership boundaries: the buyer controls the mandate, budget,
wallet and payment approval; the merchant controls the endpoint, price,
pay-to wallet, fulfillment and refunds. A merchant cannot create or widen a
buyer's mandate. AP2 checkout signing is an optional merchant capability, not
a prerequisite for an external x402 merchant to accept a buyer authorized by
Seedhape.

## Connect an AI client to Seedhape MCP

The hosted MCP endpoint is `https://www.seedhape.com/mcp` (remote Streamable
HTTP). Add it to the AI client once, authenticate with the Seedhape account,
then enable/select the Seedhape tools in the conversation. Pasting this guide
does not itself connect the MCP server. A merchant can use `publish_product`
to list a hosted API after explicitly asking; other tools remain available for
buyer setup and purchases.

- **Codex:** run `codex mcp add Seedhape --url https://www.seedhape.com/mcp`.
  If Codex prints “MCP server may or may not require login,” follow its hint
  with `codex mcp login Seedhape`, complete browser sign-in if prompted, and
  run `codex mcp list`. Reload the chat and verify tool access by calling
  `commerce_catalog`.
- **ChatGPT:** on the web, use **Settings → Apps → Create app/Add custom
  connector**, provide the URL, complete authentication and tool scanning,
  then enable it for the chat. Developer mode/custom connectors may require
  a supported plan and workspace-admin approval.
- **Claude Code:** run
  `claude mcp add --transport http seedhape https://www.seedhape.com/mcp`,
  then check `claude mcp list` or `/mcp` and authenticate. In a seller chat,
  ask to publish an API and provide its HTTPS URL and USDC price. **Claude web/Desktop:**
  use **Settings → Connectors → Add custom connector**, provide the URL, then
  **Connect** and enable it in the chat. Workspaces may require owner approval.
- **Google Antigravity:** add a remote MCP server in
  **Settings → Customizations → Installed MCP Servers**, or add
  `"seedhape": { "serverUrl": "https://www.seedhape.com/mcp" }` under
  `mcpServers` in `~/.gemini/config/mcp_config.json` (or workspace
  `.agents/mcp_config.json`); reload, authenticate if prompted, and verify
  connected status.

If the client lacks OAuth, create a bearer token at
`https://seedhape.com/connect` and store it in the client's secure
credential settings as `Authorization: Bearer <token>`; the token is shown
once. Never put a real token in a committed config file. See the [user and
agent guide](../SKILL.md) for fuller client setup, all hosted tools, and their
buyer-side use. If tools do not appear, first fix connection/authentication;
do not claim the MCP is connected just because this file is loaded.

## Choose the management surface

| Surface | Intended use | What it does not do |
| --- | --- | --- |
| Merchant dashboard | Create and edit products, configure hosted API/download details, inspect orders, payout setup and integration status. | It does not give the merchant control of a buyer's mandate or wallet. |
| Merchant capability endpoint | Read which integrations are configured/ready for the signed-in merchant account. | A catalog listing or environment variable alone is not proof a capability is production-ready. |
| `@seedhape/x402-merchant-sdk` | Add a paywall to a service the merchant operates. | It does not publish or manage the product in the hosted dashboard automatically. |
| Hosted Seedhape MCP | Lets the merchant publish a hosted API with `publish_product`; buyer tools search and prepare catalog purchases. | It does not change payout settings or manage merchant orders. |

For product edits, file uploads, order work, and payout settings, use
`https://seedhape.com/sell`. The capability
surface is `GET /api/merchant/capabilities`; product and order management use
the dashboard's authenticated merchant API. Do not expose its session or
administrative credentials to an agent or buyer.

## Path A: publish through the Seedhape dashboard

1. Open `https://seedhape.com/merchant/dashboard` and sign in with the
   merchant account that should own the product and orders.
2. Publish a product and choose its type: hosted API, digital download,
   license, or subscription. Provide a clear name, description, and price.
3. Crypto sales default to your Seedhape balance. Withdraw USDC to a wallet you
   control when you choose. Under Advanced settings, select **Use my own
   wallet** to send crypto directly to your own address. Card payments use
   Stripe Connect and settle to your connected Stripe account.
4. For a hosted API, enter the HTTPS upstream URL. Add an upstream bearer token
   only if required; Seedhape encrypts it and does not show it again. For a
   download, upload the private asset before publishing. Configure your own
   fulfillment for licenses/subscriptions as required by the dashboard status.
5. Publish, copy the generated paid endpoint, and check the upstream/product.
   The unpaid endpoint should return an x402 `402 Payment Required` challenge;
   a valid paid request should return the service response and settlement
   receipt. Use the dashboard's orders view to follow payment and delivery.
6. Publish accurate discovery metadata through the available catalog surfaces
   (Sonar/Bazaar). Discovery helps agents find the endpoint but does not
   guarantee service health or cause a payment.

The dashboard supports hosted product workflows such as API access and
digital delivery, with product kinds and fulfillment options depending on the
account's current capabilities. Use its product/order screens as the source
of truth for what is enabled on your account. Before announcing a product,
check the capability response and make sure the endpoint, price, pay-to
address, and fulfillment behavior agree.

Keep the upstream private where possible so buyers reach it through the paid
endpoint. Store credentials in server configuration, set only HTTPS upstreams,
and avoid logging authorization/payment headers or sensitive request bodies.

## Path B: add the SDK to your own service

The quickest start is the SDK's setup command, run in the service's folder:

```bash
npx @seedhape/x402-merchant-sdk init --pay-to 0xYourPayoutAddress
```

Optional flags: `--price 0.05`, `--route /api/weather`, `--name "Weather API"`
(in a terminal, `init` asks for anything you leave out). It writes:

- `seedhape.config.json`: network, USDC asset, payout address, price, route.
- `seedhape.config.mjs`: a ready paywall. Mount it with
  `app.use(paywall)` and set `PUBLIC_ORIGIN` to your service's HTTPS origin.
- `.seedhape/merchant-keys.json`: the signing key for checkout tokens,
  readable only by its owner. Keep it private and out of version control.

`init` never overwrites existing config files and reuses keys you already
made. It enables both EIP-3009 and ERC-7710 with the MetaMask facilitator,
which settles both. Manage keys later with:

```bash
npx @seedhape/x402-merchant-sdk keys:generate
npx @seedhape/x402-merchant-sdk keys:rotate
npx @seedhape/x402-merchant-sdk keys:jwks
```

`keys:rotate` switches to a new key and keeps old public keys so tokens
already issued still verify; `keys:jwks` prints the public keys to serve at
your JWKS URL. `--help` lists every command.

To wire it up by hand instead, install the SDK:

```bash
npm install @seedhape/x402-merchant-sdk
```

Use `baseSepolia` while testing and `base` for Base mainnet. Configure the
merchant's receiving wallet and a facilitator on the server. `payTo` must be
fixed by merchant configuration—never accept it from the buyer. Prices are
integer token base units: `50_000n` is `0.05 USDC` with six decimals.

Minimal Express example:

```ts
import express from "express";
import { base, expressPaywall, merchantConfig } from "@seedhape/x402-merchant-sdk";

const app = express();
app.use(express.json());

app.use(expressPaywall(merchantConfig(base, {
  payTo: process.env.MERCHANT_WALLET!,
  paymentMethods: ["eip3009"],
  price: ({ path }) => path === "/v1/weather"
    ? { amount: 50_000n, ...base }
    : null,
  free: ["/health", "/docs/*"],
  facilitator: { url: process.env.FACILITATOR_URL! },
  route: {
    name: "Weather API",
    description: "Current weather for a requested city",
    category: "weather",
    inputSchema: { type: "object", properties: { city: { type: "string" } } },
    outputSchema: { type: "object" },
  },
})));

app.get("/health", (_req, res) => res.json({ ok: true }));
app.get("/v1/weather", async (req, res) => {
  // Run fulfillment only after the paywall has accepted and settled payment.
  res.json({ city: req.query.city ?? "unknown", temperatureC: 24 });
});

app.listen(process.env.PORT ?? 3000);
```

Confirm the exact middleware and `merchantConfig` options against the SDK
version installed in your project. Keep health checks and docs free. For
dynamic pricing, return a price for paid routes and `null` for routes that
should remain free. `paymentMethods` defaults to `["eip3009"]`, which every
x402 facilitator settles. Add `"erc7710"` only when your facilitator settles
ERC-7710 delegations: buyers such as Seedhape prefer ERC-7710 whenever it is
offered, so advertising it without a facilitator that settles it makes
payments fail.

### Server configuration

- `MERCHANT_WALLET`: merchant-controlled EVM address that receives USDC.
- `FACILITATOR_URL`: server-side x402 facilitator endpoint. Use the correct
  facilitator for the network and scheme; configure authenticated facilitator
  clients as documented by the provider rather than passing API secrets as raw
  bearer tokens.
- Network preset: Base Sepolia for tests; Base for production. Keep asset,
  network, decimals, and payee consistent.
- Discovery: route name, description, category, input/output schemas, tags,
  docs URL, and representative output where supported.
- Receipts: persist the payment reference, payer, resource, amount, and status
  in the merchant's order/receipt store. Use a stable idempotency key for
  fulfillment so a retry cannot deliver twice.

Never commit `.env` files or expose wallet private keys, facilitator API
secrets, Stripe keys, buyer credentials, or payment headers to the browser.

## Verify the full purchase flow

1. Check the merchant's `/api/merchant/capabilities` (Seedhape-hosted) or your
   SDK configuration and confirm x402 is enabled for the intended network.
2. Request the paid endpoint without payment. Confirm it returns HTTP 402 and
   the expected amount, asset, network, recipient, and resource.
3. Pay from an authorized, funded agent wallet on a test network first. Confirm
   the handler receives the request only after payment verification and that a
   receipt/transaction reference is recorded.
4. Test your fulfillment and its idempotency independently. For downloads,
   issue short-lived grants and keep the source asset private. For licenses or
   subscriptions, make entitlement creation retry-safe.
5. Check wallet receipts and the relevant chain explorer before treating a
   failed HTTP response as proof that payment did not settle. Log provider
   correlation IDs, but redact payment credentials and customer secrets.

## Optional rails and protocols

- **MPP / Stripe:** separate from x402. Use the SDK's Stripe MPP integration
  or the hosted Stripe onboarding flow only when capability status is enabled.
  Keep Stripe secret/profile/MPP keys server-side. MPP uses its own challenge,
  credential, and receipt flow; a successful x402 test does not validate MPP.
- **Bazaar/Sonar:** discovery metadata, not payment authorization. Keep listing
  prices and endpoint schemas synchronized with the actual paywall.
- **AP2:** merchant checkout signing can attach an AP2 checkout attestation
  where configured. External x402 buyers do not require merchant AP2 support;
  buyer-side mandate enforcement remains the buyer's responsibility.
- **ACP/UCP/WebMCP/Web Bot Auth:** use only when the capability endpoint and
  dashboard show the required integration enabled. Catalog visibility alone
  does not mean checkout or identity verification is production-ready.

## MCP tools relevant to buyers of your products

Agents connected to Seedhape's hosted MCP can encounter these commerce tools:

| Tool | Buyer-facing behavior | Merchant implication |
| --- | --- | --- |
| `discover_offers` | Searches the authenticated user's Seedhape-hosted offer catalog. | Keep your own catalog metadata accurate; this is discovery only. |
| `publish_product` | Creates a hosted API listing after the merchant explicitly asks, using its HTTPS URL and USDC price. | The upstream check runs after saving; a failed check means the product needs attention before sharing. |
| `commerce_catalog` | Reads the available Seedhape commerce catalog. | A product appearing here does not mean it has been purchased. |
| `commerce_prepare_purchase` | Takes a `product_id` and returns a hosted endpoint or checkout link. | Keep the endpoint and checkout link valid; the tool does not pay. |
| `quote` | Reads an x402 quote for an exact URL. | Ensure challenge amount, network, asset, resource and recipient match the real route. |
| `pay` | Executes x402 GET/POST using the buyer's signed mandate and wallet. | Your endpoint must implement the advertised x402 scheme and fulfill only after valid payment. |
| `purchase_receipt`, `spend_history` | Let the buyer inspect Seedhape's own purchase record/history. | They are not substitutes for the merchant's settlement and order records. |
| `merchant_payment_status` | Reports Seedhape's merchant payment configuration status for the connected account. | It is informational status, not a payout or order-management action. |

This is not the complete buyer MCP reference; see the [user and agent guide](../SKILL.md)
for all buyer-side tools. The merchant does not need to install a buyer MCP
server to accept x402.

## Merchant operating checklist

1. Confirm capability status for the protocol and network you intend to offer.
2. Verify the receiving wallet from a trusted merchant-controlled source and
   confirm it can receive the configured asset on that network.
3. Keep advertised price, actual challenge, discovery metadata and fulfillment
   terms in sync. State whether pricing is per call, per item or subscription.
4. Test unpaid challenge, valid payment, rejected/expired payment, duplicate
   request, provider timeout, and fulfillment failure on a test network.
5. Persist an idempotent order/receipt keyed to a stable payment or request
   reference; reconcile it against facilitator and chain records.
6. Monitor upstream availability and provide a support path. A settled payment
   and successful delivery are separate facts; define refund/retry handling.
7. Rotate upstream credentials and facilitator secrets safely, and redact
   payment headers, buyer credentials and private request data from logs.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Unpaid call does not return 402 | Confirm paywall middleware is mounted before paid routes and the route price is not `null`. |
| No compatible payment option | Verify network, asset, decimals, payment method, recipient, and facilitator support. |
| Facilitator verification/settlement error | Inspect its response and supported schemes/networks; check merchant wallet configuration. Never ask the buyer for private keys. |
| Payment succeeded but content failed | Check handler/fulfillment logs and cancellation/refund behavior; correlate with receipt and transaction status. |
| Duplicate delivery after retry | Make order creation and fulfillment idempotent using the payment reference/order ID. |
| Product is hard to discover | Publish complete, accurate Bazaar/Sonar metadata and test the public listing separately from payment. |
| MPP is unavailable | Finish the merchant's Stripe setup, verify webhook/configuration status, and check the capability response. |

Do not infer “no charge” from a generic provider error. Verify the receipt or
on-chain transaction before retrying an uncertain payment.