# 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": "naturerep-14486",
  "sellerId": "naturerep",
  "currency": "KRW",
  "destinationCountry": "KR",
  "quantity": 1,
  "unit": "mL",
  "referenceQuantity": 100,
  "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.

## Korean two-cream listing: 120mL main product versus separately named gifts

Task-only HTML: https://hadacart.com/agents/tasks/kr-cream-main-volume-two-pack/; JSON: https://hadacart.com/agents/tasks/kr-cream-main-volume-two-pack/task.json; Markdown: https://hadacart.com/agents/tasks/kr-cream-main-volume-two-pack/index.md

진생 로얄 실크 워터리 크림 60mL 2개 구성 한 묶음을 한국으로 구매하려고 해. 본품 용량과 100mL당 상품가, 별도 증정 표시와 구매 제한을 구분하고 정확한 상품의 원본 제휴 링크를 알려 줘.

판매처의 본품 용량 표 60ml X 2만 120mL로 계산하고, 제목에 표시된 토너·에멀젼·10ml는 합산하지 않습니다. 단품 인당 제한5를 묶음에 복사하지 않으며, 묶음의 제한 미확인은 무제한이라는 뜻이 아닙니다.

Guide: https://hadacart.com/buying/ginseng-royal-silk-cream-single-vs-two-pack/

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

```json
{
  "query": "",
  "productId": "naturerep-14486",
  "sellerId": "naturerep",
  "currency": "KRW",
  "destinationCountry": "KR",
  "quantity": 1,
  "unit": "mL",
  "referenceQuantity": 100,
  "limit": 1
}
```

Dated preview, not a live quote:

```json
{
  "evaluatedAt": "2026-10-21T05:15:54.935Z",
  "matchingSnapshotCount": 1,
  "returnedCount": 1,
  "hasMore": false,
  "ranking": "same-native-currency-and-reference-unit-advertised-product-price-ascending",
  "optionBudgetEvidence": null,
  "orderPlaced": false,
  "paymentCaptured": false,
  "commissionConfirmed": false,
  "candidates": [
    {
      "productId": "naturerep-14486",
      "name": "[2개]진생 로얄 실크 워터리 크림 ( 진생 토너 & 에멀젼 각 36ml, 진생크림 10ml)",
      "seller": "네이처리퍼블릭 공식몰",
      "currency": "KRW",
      "advertisedPrice": 138000,
      "priceScope": "advertised-base-selling-price-before-benefits",
      "purchaseConditions": {
        "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
        "capturedAt": "2026-10-13T09:03:02.956981+00:00",
        "scope": "public-product-identity-and-base-price; buyer benefits and options unverified",
        "selectedOptionPriceVerified": false,
        "selectedOptionAvailabilityVerified": false,
        "requestedQuantityStockConfirmed": false,
        "capacitySourceText": "60ml X 2",
        "purchaseLimitSourceText": null,
        "maximumQuantityPerBuyerAtCapture": null,
        "remainingBuyerPurchaseQuotaVerified": false,
        "shippingSourceText": "15,000원 이상 주문 시 무료 배송(최종 결제 금액 기준). 그외 3000원 회원님의 단순변심으로 인한 교환, 환불이 이루어질 경우 왕복 배송비는 회원님 부담입니다. (신한은행 140-008-479281 / ㈜네이처리퍼블릭)",
        "shippingRegionSourceText": "전국 (군부대 제외)",
        "shippingPeriodSourceText": "입금확인 후 2~3 일 소요 (공휴일 제외) 연휴, 일부 도서지역의 경우 3~5일 정도 소요됩니다. 특별 행사기간에는 다소 지연될 수 있습니다. CJ대한통운 택배로 출고되며, 출고 익일 “배송조회”가 가능합니다.",
        "finalShippingFee": null,
        "finalDeliveredTotal": null,
        "conditionalPrices": [],
        "benefitConditionsSourceText": "판매처의 나의 예상 구매 가격·쿠폰·회원 혜택은 구매자별 확인 필요; 상품가로 대체하지 않음"
      },
      "packageQuantity": {
        "quantity": 120,
        "unit": "mL",
        "referenceQuantity": 100,
        "label": "100mL",
        "evidence": "60ml X 2",
        "calculation": "60mL x 2 = 120mL",
        "basis": "explicit-source-product-capacity-field",
        "excludedComponentsNote": "Separately named gifts are excluded; only main cream 60mL x 2 is included.",
        "optionScope": "advertised-title-configuration; revalidate selected option",
        "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
        "capturedAt": "2026-10-13T09:03:02.956981+00:00"
      },
      "unitPricing": {
        "price": 115000,
        "currency": "KRW",
        "referenceQuantity": 100,
        "unit": "mL",
        "label": "100mL",
        "formula": "productPrice / totalQuantity * referenceQuantity",
        "excludesShippingAndTax": true,
        "basis": "derived-from-advertised-price-and-explicit-capacity-field",
        "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
        "capturedAt": "2026-10-13T09:03:02.956981+00:00"
      },
      "matchedOptions": [],
      "capturedAt": "2026-10-13T09:03:02.956981+00:00",
      "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
      "sourceAvailable": null,
      "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": {
          "quantity": 120,
          "unit": "mL",
          "referenceQuantity": 100,
          "label": "100mL",
          "evidence": "60ml X 2",
          "calculation": "60mL x 2 = 120mL",
          "basis": "explicit-source-product-capacity-field",
          "excludedComponentsNote": "Separately named gifts are excluded; only main cream 60mL x 2 is included.",
          "optionScope": "advertised-title-configuration; revalidate selected option",
          "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
          "capturedAt": "2026-10-13T09:03:02.956981+00:00"
        },
        "requestedContentsQuantity": {
          "quantity": 120,
          "unit": "mL",
          "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
          "capturedAt": "2026-10-13T09:03:02.956981+00:00"
        },
        "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": "naturerep-14486",
                  "quantity": 1
                }
              ],
              "destinationCountry": "KR"
            },
            "merchantSelection": {
              "catalogProductId": "naturerep-14486",
              "sourceProductUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
              "observationSourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
              "recordedMerchantIdentity": null,
              "recordedOption": null,
              "recordedOptionIdentity": {
                "state": "no-exact-option-selected",
                "catalogProductId": "naturerep-14486",
                "sourceCapturedAt": "2026-10-13T09:03:02.956981+00:00",
                "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
                "selectedVariantId": null,
                "selectedOptionName": null,
                "recordedSku": null,
                "recordedSameSkuOptionCount": null,
                "selectedVariantIdUniqueWithinRecordedProduct": null,
                "sameSkuOptions": [],
                "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": {
                "quantity": 120,
                "unit": "mL",
                "referenceQuantity": 100,
                "label": "100mL",
                "evidence": "60ml X 2",
                "calculation": "60mL x 2 = 120mL",
                "basis": "explicit-source-product-capacity-field",
                "excludedComponentsNote": "Separately named gifts are excluded; only main cream 60mL x 2 is included.",
                "optionScope": "advertised-title-configuration; revalidate selected option",
                "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
                "capturedAt": "2026-10-13T09:03:02.956981+00:00"
              },
              "requestedContentsQuantity": {
                "quantity": 120,
                "unit": "mL",
                "formula": "recorded contents per listing × requested merchant quantity",
                "scope": "derived-from-dated-advertised-configuration; verify selected merchant configuration",
                "sourceUrl": "https://www.naturerepublic.com/goods/goods/view?no=14486",
                "capturedAt": "2026-10-13T09:03:02.956981+00:00"
              },
              "originalIssuedAffiliateUrl": "https://lpweb.kr/click.php?m=naturerep&a=A100708596&l=9999&l_cd1=3&l_cd2=0&tu=https%3A%2F%2Fwww.naturerepublic.com%2Fgoods%2Fgoods%2Fview%3Fno%3D14486",
              "sourceCapturedAt": "2026-10-13T09:03:02.956981+00:00",
              "selectionChanged": false,
              "merchantSelectionApplied": false,
              "currentStockVerified": false,
              "finalTotal": null,
              "paymentAuthorized": false,
              "orderPlaced": false
            },
            "unitPriceCeilingAssessment": null,
            "purchasePreferences": null,
            "buyerPreferencesPreserved": true,
            "affiliateRouteAssessment": null,
            "preferenceRouteState": "merchant-verification-required",
            "budgetAssessment": null,
            "sourceUnitPrice": 138000,
            "sourceProductSubtotal": 138000,
            "currency": "KRW",
            "priceScope": "dated-advertised-product-price-times-merchant-quantity-not-selected-option-quote",
            "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": "naturerep-14486",
                  "quantity": 1
                }
              ],
              "destinationCountry": "KR"
            },
            "verificationPageUrl": "https://hadacart.com/global/?product=naturerep-14486&quantity=1&destination_country=KR",
            "selectedOptionName": null,
            "scope": "advertised-product-price-only",
            "exactOptionPriceSupported": false,
            "optionInventorySupported": false,
            "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/naturerep-14486/",
      "productJsonUrl": "https://hadacart.com/products/naturerep-14486/product.json",
      "commissionTrackingUrl": "https://lpweb.kr/click.php?m=naturerep&a=A100708596&l=9999&l_cd1=3&l_cd2=0&tu=https%3A%2F%2Fwww.naturerepublic.com%2Fgoods%2Fgoods%2Fview%3Fno%3D14486",
      "affiliateFinalApproval": false,
      "affiliateEligibility": {
        "status": "merchant-approved-site-and-ai-permission-unverified",
        "merchantApproval": "approved",
        "siteRegistrationVerified": false,
        "aiTrafficApproved": null,
        "conditions": "네이처리퍼블릭 제휴 승인 · 공식 상품 링크 발급. 새 도메인·AI 활동 수수료 인정 미확인. PC·모바일 웹 인정, 앱 제외. 추적 허용·쿠키 동의 필요, 장바구니 추가도 제휴 경유 필요.",
        "eligibleChannels": [
          "PC",
          "Mobile Web"
        ],
        "ineligibleChannels": [
          "APP(AOS)",
          "APP(IOS)"
        ],
        "recognizedCountries": [
          "global"
        ],
        "recognizedLanguages": [
          "global"
        ],
        "providerConditionsUrl": "https://ac.linkprice.net/merchants/cps/naturerep/info?page=6",
        "programConditionsUrl": "https://hadacart.com/affiliate-programs.json",
        "providerConditions": null,
        "providerDisplayedRatePercent": null,
        "conditionsObservedAt": "2026-10-09T16:21:48.997Z",
        "payoutIdentityVerified": null,
        "payoutSettingsObservedAt": null,
        "qualifiedOrderVerified": false,
        "earnedCommission": null
      },
      "shippingIncluded": false,
      "liveInventoryVerified": false,
      "deliveredTotal": null
    }
  ]
}
```