# 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": "Keychron Q4 QMK Custom Mechanical Keyboard",
  "productId": "keychron-7040384794713",
  "optionQuery": "Fully Assembled / Shell White / Gateron G Pro Brown",
  "optionQueryMode": "exact",
  "sellerId": "keychron",
  "currency": "USD",
  "destinationCountry": "US",
  "destinationRegion": "NY",
  "quantity": 1,
  "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 Q4 Shell White assembled Brown: exact option, included parts and source code exclusion

Task-only HTML: https://hadacart.com/agents/tasks/us-q4-shell-white-assembled-brown/; JSON: https://hadacart.com/agents/tasks/us-q4-shell-white-assembled-brown/task.json; Markdown: https://hadacart.com/agents/tasks/us-q4-shell-white-assembled-brown/index.md

For one Keychron Q4 Fully Assembled / Shell White / Gateron G Pro Brown for US NY delivery, retain that exact option and80USD unit ceiling. Explain the dated source included-parts and no-discount-code declaration; do not substitute a cheaper unavailable Barebone or a different color.

The exact Q4-K3 identity and79.99USD dated option are separate from59.99USD source-unavailable Barebone. Retained primary body declares assembled parts, Barebone exclusions and no discount codes; not current code/stock/delivery or a payment authorization.

Guide: https://hadacart.com/buying/keychron-q4-assembled-barebone-included-parts/

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

```json
{
  "query": "Keychron Q4 QMK Custom Mechanical Keyboard",
  "productId": "keychron-7040384794713",
  "optionQuery": "Fully Assembled / Shell White / Gateron G Pro Brown",
  "optionQueryMode": "exact",
  "sellerId": "keychron",
  "currency": "USD",
  "destinationCountry": "US",
  "destinationRegion": "NY",
  "quantity": 1,
  "maxOptionPrice": 80,
  "limit": 1
}
```

Dated preview, not a live quote:

```json
{
  "evaluatedAt": "2026-10-21T05:15:35.284Z",
  "matchingSnapshotCount": 1,
  "returnedCount": 1,
  "hasMore": false,
  "ranking": "catalog-order-no-price-ranking",
  "optionBudgetEvidence": null,
  "orderPlaced": false,
  "paymentCaptured": false,
  "commissionConfirmed": false,
  "candidates": [
    {
      "productId": "keychron-7040384794713",
      "name": "Keychron Q4 QMK Custom Mechanical Keyboard",
      "seller": "Keychron",
      "currency": "USD",
      "advertisedPrice": 79.99,
      "priceScope": "lowest-available-option-price",
      "purchaseConditions": null,
      "packageQuantity": null,
      "unitPricing": null,
      "matchedOptions": [
        {
          "id": "40097512095833",
          "name": "Fully Assembled / Shell White / Gateron G Pro Brown",
          "price": 79.99,
          "currency": "USD",
          "available": true,
          "sku": "Q4-K3",
          "recordedOptionIdentity": {
            "state": "selected-sku-unique-within-recorded-product",
            "catalogProductId": "keychron-7040384794713",
            "sourceCapturedAt": "2026-10-08T13:54:25.711874+00:00",
            "sourceUrl": "https://www.keychron.com/products.json?limit=250&page=2",
            "selectedVariantId": "40097512095833",
            "selectedOptionName": "Fully Assembled / Shell White / Gateron G Pro Brown",
            "recordedSku": "Q4-K3",
            "recordedSameSkuOptionCount": 1,
            "selectedVariantIdUniqueWithinRecordedProduct": true,
            "sameSkuOptions": [
              {
                "variantId": "40097512095833",
                "name": "Fully Assembled / Shell White / Gateron G Pro Brown"
              }
            ],
            "optionsTruncated": false,
            "scope": "case-sensitive-SKU-only-within-this-dated-product; not global uniqueness, a merchant selection or stock confirmation",
            "skuAloneSelectsExactCurrentOption": false,
            "requiresExactRecordedVariantIdAndName": true,
            "selectionChanged": false,
            "currentMerchantSelectionVerified": false,
            "requestedQuantityStockConfirmed": false
          },
          "priceScope": "recorded-option-price-not-current-quote",
          "availabilityScope": "recorded-option-availability-not-current-stock",
          "sourceUrl": "https://www.keychron.com/products.json?limit=250&page=2",
          "capturedAt": "2026-10-08T13:54:25.711874+00:00",
          "availabilityCheckedAt": "2026-10-08T13:54:25.711874+00:00",
          "livePriceVerified": false,
          "liveInventoryVerified": false,
          "requestedQuantityStockConfirmed": false,
          "deliveredTotal": null,
          "orderPlaced": false
        }
      ],
      "capturedAt": "2026-10-08T13:54:25.711874+00:00",
      "sourceUrl": "https://www.keychron.com/products.json?limit=250&page=2",
      "sourceAvailable": true,
      "routeState": "merchant-verification-required",
      "purchasePreferences": null,
      "buyerPreferencesPreserved": true,
      "affiliateRouteAssessment": null,
      "affiliateRouteSelected": true,
      "quantityAssessment": {
        "requestedMerchantQuantity": 1,
        "quantityIsExample": false,
        "scope": "merchant listing units or packages, not individual contents",
        "recordedPackageQuantity": null,
        "requestedContentsQuantity": null,
        "maximumQuantityPerBuyerAtCapture": null,
        "sourceQuantityLimitExceeded": false,
        "quantityLimitScope": "dated merchant declaration; current limit and stock allocation unverified",
        "currentQuantityStockVerified": false,
        "quantityAllocated": false,
        "selectionChanged": false,
        "orderPlaced": false
      },
      "purchasePreparation": {
        "requestExecuted": false,
        "cartCreated": false,
        "paymentAuthorized": false,
        "orderPlaced": false,
        "plans": [
          {
            "status": "merchant-verification-required",
            "method": "POST",
            "endpoint": "https://hadacart.com/api/purchase/prepare",
            "request": {
              "items": [
                {
                  "productId": "keychron-7040384794713",
                  "variantId": "40097512095833",
                  "quantity": 1,
                  "unitPriceCeiling": {
                    "amount": 80,
                    "currency": "USD"
                  }
                }
              ],
              "destinationCountry": "US",
              "destinationRegion": "NY"
            },
            "merchantSelection": {
              "catalogProductId": "keychron-7040384794713",
              "sourceProductUrl": "https://www.keychron.com/products/keychron-q4-qmk-via-custom-mechanical-keyboard",
              "observationSourceUrl": "https://www.keychron.com/products.json?limit=250&page=2",
              "recordedMerchantIdentity": null,
              "recordedOption": {
                "variantId": "40097512095833",
                "name": "Fully Assembled / Shell White / Gateron G Pro Brown",
                "sku": "Q4-K3"
              },
              "recordedOptionIdentity": {
                "state": "selected-sku-unique-within-recorded-product",
                "catalogProductId": "keychron-7040384794713",
                "sourceCapturedAt": "2026-10-08T13:54:25.711874+00:00",
                "sourceUrl": "https://www.keychron.com/products.json?limit=250&page=2",
                "selectedVariantId": "40097512095833",
                "selectedOptionName": "Fully Assembled / Shell White / Gateron G Pro Brown",
                "recordedSku": "Q4-K3",
                "recordedSameSkuOptionCount": 1,
                "selectedVariantIdUniqueWithinRecordedProduct": true,
                "sameSkuOptions": [
                  {
                    "variantId": "40097512095833",
                    "name": "Fully Assembled / Shell White / Gateron G Pro Brown"
                  }
                ],
                "optionsTruncated": false,
                "scope": "case-sensitive-SKU-only-within-this-dated-product; not global uniqueness, a merchant selection or stock confirmation",
                "skuAloneSelectsExactCurrentOption": false,
                "requiresExactRecordedVariantIdAndName": true,
                "selectionChanged": false,
                "currentMerchantSelectionVerified": false,
                "requestedQuantityStockConfirmed": false
              },
              "requestedMerchantQuantity": 1,
              "merchantQuantityScope": "number-of-listed-product-configurations-or-packages; not individual contents",
              "recordedPackageQuantity": null,
              "requestedContentsQuantity": null,
              "originalIssuedAffiliateUrl": "https://www.keychron.com/products/keychron-q4-qmk-via-custom-mechanical-keyboard?ref=pfuqblvp",
              "sourceCapturedAt": "2026-10-08T13:54:25.711874+00:00",
              "selectionChanged": false,
              "merchantSelectionApplied": false,
              "currentStockVerified": false,
              "finalTotal": null,
              "paymentAuthorized": false,
              "orderPlaced": false
            },
            "unitPriceCeilingAssessment": {
              "ceiling": {
                "amount": 80,
                "currency": "USD"
              },
              "state": "merchant-current-option-price-required",
              "observedUnitPrice": 79.99,
              "observedCurrency": "USD",
              "priceEvidence": "dated-source",
              "observedAt": "2026-10-08T13:54:25.711874+00:00",
              "currencyComparable": true,
              "unitPriceExceedsCeiling": false,
              "ceilingChanged": false,
              "selectionChanged": false,
              "currencyConversionPerformed": false,
              "currentExactOptionPriceVerified": false,
              "requiresBuyerReview": true,
              "buyerAcceptedChanges": false,
              "withinDeliveredBudget": null,
              "deliveredTotal": null,
              "paymentAuthorized": false,
              "scope": "one selected merchant listing/configuration; excludes quantity multiplication, shipping/tax and buyer-specific benefit eligibility"
            },
            "purchasePreferences": null,
            "buyerPreferencesPreserved": true,
            "affiliateRouteAssessment": null,
            "preferenceRouteState": "merchant-verification-required",
            "budgetAssessment": null,
            "sourceUnitPrice": 79.99,
            "sourceProductSubtotal": 79.99,
            "currency": "USD",
            "priceScope": "dated-exact-option-price-times-merchant-quantity",
            "perUnitPriceCeilingUnchanged": true,
            "quantityIsExample": false,
            "destinationCopiedFromRequest": true,
            "requestIsExample": true,
            "requestExecuted": false,
            "sourceCurrentPriceVerified": false,
            "requestedQuantityStockVerified": false,
            "deliveredTotal": null,
            "buyerPaymentAuthorized": false,
            "orderPlaced": false
          }
        ],
        "status": "read-only-merchant-selection-preparation-plans"
      },
      "purchaseVerification": {
        "requestExecuted": false,
        "stockReservation": false,
        "cartCreationAuthorized": false,
        "paymentAuthorized": false,
        "plans": [
          {
            "method": "POST",
            "endpoint": "https://hadacart.com/api/purchase/revalidate",
            "request": {
              "items": [
                {
                  "productId": "keychron-7040384794713",
                  "variantId": "40097512095833",
                  "quantity": 1,
                  "unitPriceCeiling": {
                    "amount": 80,
                    "currency": "USD"
                  }
                }
              ],
              "destinationCountry": "US",
              "destinationRegion": "NY"
            },
            "verificationPageUrl": "https://hadacart.com/global/?product=keychron-7040384794713&quantity=1&destination_country=US&variant=40097512095833&unit_ceiling_amount=80&unit_ceiling_currency=USD&destination_region=NY",
            "selectedOptionName": "Fully Assembled / Shell White / Gateron G Pro Brown",
            "scope": "exact-option-price-and-source-availability",
            "exactOptionPriceSupported": true,
            "optionInventorySupported": true,
            "requestIsExample": true,
            "quantityIsExample": false,
            "quantityCopiedFromRequest": true,
            "destinationCopiedFromRequest": true,
            "requestExecuted": false,
            "sourceMayReturnDatedCache": true,
            "cacheTtlSeconds": 600,
            "originalAffiliateUrlModified": false,
            "stockReservation": false,
            "cartCreationAuthorized": false,
            "paymentAuthorized": false,
            "instructions": "Preserve the supplied merchant listing quantity. Preserve buyer preferences in any later route assessment. Destination is copied from this candidate request; verify the actual buyer destination. Review at the verification page or explicitly request the read-only source check. Advertised product price is not selected-option price or stock. Current stock, requested-quantity allocation, delivery, shipping, tax and final payable total are not guaranteed. Reading this plan executes no request, affiliate visit, cart, order or payment."
          }
        ],
        "status": "read-only-source-verification-plans"
      },
      "requestIsExample": true,
      "detailUrl": "https://hadacart.com/products/keychron-7040384794713/",
      "productJsonUrl": "https://hadacart.com/products/keychron-7040384794713/product.json",
      "commissionTrackingUrl": "https://www.keychron.com/products/keychron-q4-qmk-via-custom-mechanical-keyboard?ref=pfuqblvp",
      "affiliateFinalApproval": false,
      "affiliateEligibility": {
        "status": "issued-product-link-ai-and-qualified-order-eligibility-unverified",
        "merchantApproval": "account-active-in-authenticated-portal",
        "siteRegistrationVerified": true,
        "aiTrafficApproved": null,
        "conditions": "키크론 공식 상품 링크 발급 · hadacart.com 프로필 저장 확인. 첫 구매자 적격 구매 5% 안내, 예약판매 제외. 쿠키 7일·다른 경유로 덮어쓰기 가능·30일 검증. PayPal 최소 300 USD, 검증 후 Net15. AI 활동·장바구니/결제 추적·정산 신원·실제 수익 미확인.",
        "eligibleChannels": null,
        "ineligibleChannels": null,
        "recognizedCountries": null,
        "recognizedLanguages": null,
        "providerConditionsUrl": "https://affiliate.keychron.com/program-details/commissions",
        "programConditionsUrl": null,
        "providerConditions": {
          "firstTimeCustomerOnly": true,
          "preOrdersExcluded": true,
          "validationDays": 30,
          "cookieDays": 7,
          "shippingTaxExcluded": true,
          "payoutMethod": "PayPal",
          "payoutWithinDaysAfterValidation": 15,
          "cookieOverwritePossible": true,
          "minimumPayoutUSD": 300
        },
        "providerDisplayedRatePercent": 5,
        "conditionsObservedAt": "2026-10-09T02:05:21.990Z",
        "payoutIdentityVerified": false,
        "payoutSettingsObservedAt": "2026-10-09T02:16:25.088760+00:00",
        "qualifiedOrderVerified": false,
        "earnedCommission": null
      },
      "shippingIncluded": false,
      "liveInventoryVerified": false,
      "deliveredTotal": null
    }
  ]
}
```