# Hadacart: use a buying task / 구매 과제로 사용하기

Buying-question directory: https://hadacart.com/api/buying/guides ; Markdown: https://hadacart.com/buying/questions/index.md . Filter guide example country/currency/merchant/unit/keywords; not product delivery or an actual buyer selection. Authorized platform MCP: find_buying_guides.

- Replace the example destination and constraints with the actual buyer choices. California is an example, not every US buyer.
- Read-only candidate requests do not open affiliate links or create carts. No-match results never relax exact identity, option or budget.
- Revalidate current price/stock and verify delivery/final total at the merchant; snapshots are dated.
- Keep the original provider-issued link and merchant browser session for a buyer-approved purchase; AI and cart attribution remain unverified.
- A copied prompt, connected tool or own QA run is not an independent purchaser, qualified order or earned commission.

Connection: https://hadacart.tiny-deer-9667.chatgpt.site/mcp
Existing Sites-provisioned personal plugin; client installation/authorization is separate. This does not enroll all ChatGPT users or grant checkout/payment permission.

## Public MCP input recovery

Tool errors keep isError=true and return structuredContent.error plus structuredContent.recovery. These are documentation only; no request has been repaired or retried.

- Call tools/list for the current input schema. Do not repeat the same failing request unchanged.
- find_purchase_candidates requires query, one native currency and destinationCountry. Use the actual buyer destination; US additionally needs the actual region to assess a purchase handoff.
- optionQuery and maxOptionPrice require sellerId and one native currency, even when productId is provided. Preserve the exact option, quantity, budget, benefits and product constraints. Never remove them just to obtain a result.
- For get_product, copy an exact products[].id from search_products or candidates[].productId from find_purchase_candidates. A title, variant ID, merchant URL or invented prefix is not a product ID. Unknown IDs are not replaced automatically.
- If required buyer choices are missing, obtain them from the buyer. The KR and US examples below are diagnostic documentation, never defaults or buyer consent.
- After correcting the input, review source dates, exact options and destination conditions. Keep the original issued affiliate URL and reselect actual options/quantity at merchant; delivery, final total, payment approval, qualified order and commission need separate evidence.

Diagnostic examples only; replace with actual buyer choices. Send X-Hadacart-Traffic-Purpose: diagnostic when testing:

```json
[
  {
    "label": "KR native-KRW udon example only",
    "tool": "find_purchase_candidates",
    "arguments": {
      "query": "우동",
      "currency": "KRW",
      "destinationCountry": "KR",
      "sellerId": "pulmuone",
      "quantity": 1,
      "limit": 3
    }
  },
  {
    "label": "US native-USD exact K2 Brown example only; NY and quantity2 are not buyer defaults",
    "tool": "find_purchase_candidates",
    "arguments": {
      "query": "K2",
      "currency": "USD",
      "destinationCountry": "US",
      "destinationRegion": "NY",
      "sellerId": "keychron",
      "productId": "keychron-4328395079769",
      "optionQuery": "Brown",
      "quantity": 2,
      "budget": {
        "amount": 140,
        "currency": "USD"
      },
      "maxOptionPrice": 70,
      "limit": 3
    }
  }
]
```

## Runnable KR/US MCP client example

Download and inspect [https://hadacart.com/public-catalog-client.mjs](https://hadacart.com/public-catalog-client.mjs). In a separate local directory, install the pinned official SDK dependency, then run the fixed Korean or US diagnostic example:

```sh
npm install --save-exact @modelcontextprotocol/client@2.3.1
node public-catalog-client.mjs kr
node public-catalog-client.mjs us
```

Own integration check: 2026-10-19T18:42:26.758Z, Node v26.5.0, @modelcontextprotocol/client@2.3.1, negotiated MCP 2025-11-25. The SDK performs initialization and notification automatically; this stateless endpoint returns405 for its optional GET subscription. Both candidate lookups succeeded without credentials. Other client/version compatibility remains unverified.

KR keeps the dated welcome-deal membership/other-goods/standalone restrictions. US keeps the exact K3P-H3 option, NY/USD/quantity1 and buyer ceilings; its recorded unavailable flag means no preparation plan. The complete returned snapshot, source dates, original issuer links and unknown delivery/final total remain in the output.

Every example request is marked diagnostic, including the task download. Do not use these runs as buyer visits, selections, merchant clicks, orders or commission. The code does not follow affiliate URLs or invoke preparation/payment. For a real lookup use the actual buyer constraints in your own client; do not treat this fixed example as consent or remove diagnostic marking to fabricate traffic. No API keys or personal data are needed.

## Public read-only catalog MCP

Endpoint: https://hadacart.com/api/catalog/mcp

Registry metadata listing: [com.hadacart/catalog-snapshots 1.0.0](https://registry.modelcontextprotocol.io/v0.1/servers/com.hadacart%2Fcatalog-snapshots/versions/1.0.0). Recorded status: active; published 2026-10-21T01:22:49.120624Z; verified 2026-10-21T01:23:02.651Z. Metadata listing is not client installation, endorsement, buyer traffic, order or commission evidence.

Streamable HTTP with stateless JSON responses. Configure the endpoint in your own authorized client; send no Authorization, Cookie, API key or personal data. POST with Content-Type: application/json and Accept: application/json, text/event-stream. Initialize, send notifications/initialized, then tools/list or tools/call. Only find_buying_guides, find_purchase_candidates, search_products and get_product are exposed. Use actual buyer country, currency, exact product/option, quantity and budget. Integration tests should add X-Hadacart-Traffic-Purpose: diagnostic.

This exposes already-public dated data. Native Sites OAuth and connected-app permissions remain separate. No private reports, merchant requests, affiliate activation, cart, checkout, payment or order tools. Registry listing does not configure clients or guarantee compatibility or referrals.

## Supported connection paths

Public read-only HTTP: https://hadacart.com/api/buying/candidates; credentials omit.

Platform-managed MCP: https://hadacart.tiny-deer-9667.chatgpt.site/mcp; OAuth resource https://hadacart.tiny-deer-9667.chatgpt.site/mcp. Sites manages client connection and authorization; an existing installed client read was verified at 2026-10-13T19:25:46.355Z. Arbitrary/anonymous client compatibility and automatic distribution are unverified. Raw canonical https://hadacart.com/mcp anonymous POST returned404 at 2026-10-13T19:24:39.640610+00:00; cause not established. Use public HTTP for credential-free catalog comparison. Preserve platform OAuth and client permissions.

Machine-readable metadata: https://hadacart.com/.well-known/agent-connection.json

## Public HTTP integration, without the personal plugin

An approved browser or server agent can call the public candidate API directly, without a Site plugin, account credential or merchant login. This does not distribute a tool automatically to other AI users. Client/tool installation and outbound network approval belong to the buyer's client. Replace the example country and constraints with the buyer choices.

```javascript
const response = await fetch("https://hadacart.com/api/buying/candidates", {
  method: "POST",
  credentials: "omit",
  headers: {"Content-Type": "application/json", "X-Hadacart-Traffic-Purpose": "diagnostic"},
  body: JSON.stringify({
  "query": "",
  "productId": "keychron-6576777199705",
  "sellerId": "keychron",
  "optionQuery": "RGB Backlight Aluminum Frame / Keychron Super Switch (Hot-Swappable) / Brown",
  "optionQueryMode": "exact",
  "currency": "USD",
  "destinationCountry": "US",
  "destinationRegion": "CA",
  "maxOptionPrice": 80,
  "limit": 1
})
});
if (!response.ok) throw new Error("Hadacart returned HTTP " + response.status);
const shortlist = await response.json();
```

The diagnostic header marks integration tests. For a real buyer request omit that header; never send cookies, keys, card data, addresses, emails or other personal data. Only the documented public search fields are accepted. Returning original affiliate links does not activate them, create a cart or order. Verify eligibility, current merchant conditions and buyer consent separately.

## US Keychron K10: check exact RGB aluminum hot-swap Brown against $80

Task-only HTML: https://hadacart.com/agents/tasks/us-k10-exact-brown-budget/; JSON: https://hadacart.com/agents/tasks/us-k10-exact-brown-budget/task.json; Markdown: https://hadacart.com/agents/tasks/us-k10-exact-brown-budget/index.md

For US delivery, find the Keychron K10 RGB aluminum-frame hot-swappable Brown configuration with an option unit price no higher than 80 USD. Keep that exact configuration; do not use the product minimum or silently substitute a non-hot-swap option.

The complete recorded option name and exact catalog product ID stay fixed while the USD option ceiling is checked. A cheap product minimum cannot stand in for this configuration. No-match evidence explains the dated price without raising the ceiling; no delivery, current-stock or payment promise.

Guide: https://hadacart.com/buying/keychron/

POST https://hadacart.com/api/buying/candidates / MCP find_purchase_candidates

```json
{
  "query": "",
  "productId": "keychron-6576777199705",
  "sellerId": "keychron",
  "optionQuery": "RGB Backlight Aluminum Frame / Keychron Super Switch (Hot-Swappable) / Brown",
  "optionQueryMode": "exact",
  "currency": "USD",
  "destinationCountry": "US",
  "destinationRegion": "CA",
  "maxOptionPrice": 80,
  "limit": 1
}
```

Dated preview, not a live quote:

```json
{
  "evaluatedAt": "2026-10-21T05:17:35.216Z",
  "matchingSnapshotCount": 0,
  "returnedCount": 0,
  "hasMore": false,
  "ranking": "catalog-order-no-price-ranking",
  "optionBudgetEvidence": {
    "reason": "recorded-exact-option-prices-exceed-ceiling",
    "scope": "bounded-dated-same-option-evidence-not-purchase-alternatives",
    "onlyRemovedFilter": "maxOptionPrice",
    "preservedFilters": {
      "query": "",
      "productId": "keychron-6576777199705",
      "sellerId": "keychron",
      "optionQuery": "RGB Backlight Aluminum Frame / Keychron Super Switch (Hot-Swappable) / Brown",
      "optionQueryMode": "exact",
      "currency": "USD",
      "destinationCountry": "US",
      "destinationRegion": "CA",
      "limit": 1,
      "affiliateLinkedOnly": true,
      "availableOnly": false,
      "sort": "default"
    },
    "requestedCeiling": 80,
    "currency": "USD",
    "matchingProductCount": 1,
    "examinedProductCount": 1,
    "hasMoreUnexaminedProducts": false,
    "examinedOptionCount": 1,
    "unknownPriceOptionCount": 0,
    "lowestExaminedExactOptionPrice": 82.99,
    "amountAboveCeiling": 2.99,
    "lowestPricedOptions": [
      {
        "productId": "keychron-6576777199705",
        "productName": "Keychron K10 Wireless Mechanical Keyboard",
        "variantId": "39426678325337",
        "optionName": "RGB Backlight Aluminum Frame / Keychron Super Switch (Hot-Swappable) / Brown",
        "price": 82.99,
        "currency": "USD",
        "sourceAvailable": false,
        "capturedAt": "2026-10-12T12:52:43.914619+00:00",
        "availabilityCheckedAt": "2026-10-12T12:52:43.914619+00:00",
        "sourceUrl": "https://www.keychron.com/products.json?limit=250&page=3",
        "priceScope": "recorded-option-price-not-current-quote",
        "shippingAssessment": {
          "destination": {
            "country": "US",
            "region": "CA"
          },
          "scope": "merchant-published-policy-not-product-quote",
          "policyStatus": "country-section-observed",
          "blockedByPublishedPolicy": false,
          "reason": null,
          "countrySectionObserved": true,
          "remoteAreaChargeDeclaration": {
            "sourceUrl": "https://www.keychron.com/pages/shipping-policy",
            "capturedAt": "2026-10-16T14:01:23.139778+00:00",
            "sourceHash": "352508e0c89009be3af9c0f90b58ea2f734e70b136d257928e90c21cdde0ae30",
            "sourceSection": "Remote Area Shipping Cost",
            "namedUSRegionCodes": [
              "PR",
              "GU",
              "VI"
            ],
            "equivalentISOCountryCodes": [
              "PR",
              "GU",
              "VI"
            ],
            "sourceAmount": 35,
            "sourceCurrencySymbol": "$",
            "currency": null,
            "currencyScope": "Source paragraph uses $ without an explicit ISO currency code; never assumed or added to USD subtotal.",
            "sourceText": "Puerto Rico, Guam, US Virgin Islands are required to pay $35 additional cost as per the quote from DHL. Shipping cost does NOT include extra costs defined as remote area shipping fees on DHL’s website.",
            "otherRemotePostcodesMayBeCharged": true,
            "postcodeVerified": false,
            "buyerChargeConfirmed": false,
            "payableShippingAmount": null,
            "finalDeliveredTotal": null,
            "application": "postcode-dependent-not-verified",
            "destination": {
              "country": "US",
              "region": "CA"
            }
          },
          "sourceUrl": "https://www.keychron.com/pages/shipping-policy",
          "capturedAt": "2026-10-16T14:01:23.139778+00:00",
          "addressRestrictions": [
            "APO, DPO and PO boxes excluded",
            "Forwarding addresses excluded",
            "Some Spanish provinces and European island addresses excluded; verify the exact address at merchant",
            "Delivery address must be accepted by the merchant's carrier"
          ],
          "productDeliveryAvailable": null,
          "postcodeVerified": false,
          "shippingAmount": null,
          "taxAmount": null,
          "deliveredTotal": null,
          "requiresMerchantQuote": true
        }
      }
    ],
    "lowestPricedOptionsTruncated": false,
    "automaticFilterChange": false,
    "currentPriceVerified": false,
    "currentInventoryVerified": false,
    "deliveredTotal": null,
    "buyerSpendingAuthorization": false,
    "orderPlaced": false
  },
  "orderPlaced": false,
  "paymentCaptured": false,
  "commissionConfirmed": false,
  "candidates": []
}
```