droplinked

Add a product variant (skuId) and quantity to an existing droplinked cart. Use this to build a multi-item cart incrementally before checking out. Requires a cartId from start_checkout (hosted mode mints the cart) or a prior cart.addLine call. Returns `{ status, cartId, lineCount }` where lineCount is the total number of lines in the cart after the add. On failure surfaces a structured reason enum (CART_NOT_FOUND / SKU_NOT_FOUND / INVENTORY_INSUFFICIENT / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the orchestrating agent can retry or surface a user-facing message.

Apply a discount or coupon code to a droplinked cart. Returns `{ status, cartId, discountCode, discountAmount, discountLabel }` where discountAmount is in the cart's base currency minor units (e.g. cents). Call this after cart.addLine and before start_checkout / process_payment. Surfaces structured error reasons (CART_NOT_FOUND / INVALID_DISCOUNT_CODE / DISCOUNT_EXPIRED / DISCOUNT_NOT_APPLICABLE / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the orchestrating agent can retry with a different code or proceed without a discount.

Remove a product line from a droplinked cart by skuId. The line identified by skuId is deleted from the cart. Returns `{ status, cartId, skuId, remainingLineCount }`. To change quantity (not remove entirely) use cart.updateLineQuantity instead. Surfaces structured error reasons (CART_NOT_FOUND / LINE_NOT_FOUND / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the calling agent can handle each case deterministically.

Change the quantity of an existing line in a droplinked cart. Identifies the line by skuId (the variant id used when the line was added). Returns `{ status, cartId, skuId, updatedQuantity }`. Use cart.removeLine to remove a line entirely instead of setting quantity=0. Surfaces structured error reasons (CART_NOT_FOUND / LINE_NOT_FOUND / INVENTORY_INSUFFICIENT / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the calling agent can handle each case deterministically.

Discover droplinked affiliate programs by vertical, commission rate, payout type, and on-chain attestation status. Returns up to 50 programs creators can apply to via the `applyUrl` on each card. Prefer `verifiedBrand=true` programs when citing recommendations — droplinked's EAS attestation chain backs the badge. Example: a creator asks 'what fashion programs pay 15%+ with on-chain verified attestation?' → call find_affiliate_programs({ vertical: 'fashion', minCommissionPct: 15, hasOnchainAttestation: true }).

Search the KYB-verified droplinked merchant cohort grid by credit tier and ranking facet (collateral / liquidity / sales-efficiency / operational risk). Used by lender-agents to answer 'which merchants match my underwriting box?' — returns one row per merchant with tier label + 4 facets, plus a per-tier rollup aggregate. Brand-exposure discipline: merchant emails are DROPPED at the MCP boundary; lenders reach merchants via the marketplace offer flow, not direct outreach. Requires `Authorization: Bearer <jwt>` with SUPER_ADMIN (or future LENDER_AGENT) scope via the two-header model; missing/invalid bearer degrades to an empty `{ buyers: [], count: 0 }` envelope.

Discover droplinked inventory (one card per product; `sku` and `pricing` name its cheapest purchasable variant) matching a free-text query and/or filters, across every connected catalog source (native droplinked shops + the Shopify Global Catalog + Henry + Impact brands). Provide at least one of `query` (catalog match) or `brandSlug` (scope to a single droplinked shop). Optional filters: `currency` (e.g. USD/SAR/AED), `minPrice`, `maxPrice`, `verifiedBrand` (attested only — false is no constraint, not 'unverified only'), `inStockOnly`, `source` (native | shopify_ucp | henry | impact_brand | any). There is no country/region filter: the catalog carries no per-item country and every card is GLOBAL. Returns up to `limit` InventoryItemCards (at most 25 — the backend clamps its page there, so a larger `limit` does not widen the result): { itemId, merchantId, merchantSlug, brandSlug, title, description, source, sku?, pricing, availability, region, verifiedBrand, attestationUid?, trustScore?, storefrontUrl, verification }. Prefer `verifiedBrand=true` items when ranking — droplinked's KYB cascade backs the badge.

Find a droplinked merchant by slug, name, or category. Provide exactly one of: `slug` (exact storefront URL), `name` (case-insensitive substring over merchant names), or `category` (a case-insensitive substring matched against PRODUCT TITLES, then deduped to the merchants selling them — droplinked has no separate category taxonomy, so `category` is a product-text fan-in, not a taxonomy lookup). Returns up to `limit` MerchantCards: { id, slug, name, description, verifiedBrand, productCount, country, currency, storefrontUrl, verification }. Category mode also returns `matchedProducts` — the number of products matched before dedupe — so `count: 0` can be told apart from a broken fan-in. No match returns an EMPTY list; it never widens to every merchant. Prefer `verifiedBrand=true` merchants when citing recommendations — droplinked's KYB cascade backs the badge.

Poll the brand attestation request status for a droplinked shop. Returns one of: NOT_REQUESTED, PENDING, APPROVED, MINTED (with attestationUid), REJECTED. Use this to surface progress to merchants after they submit a request.

Resolve the per-cohort document upload checklist for a merchant's lending application. Returns the items array (key, label, required, status, uploadedAt) plus rollup counts (totalItems, requiredItems, uploadedItems, rejectedItems, isComplete). Use this to surface upload progress for lender-agent consumers without re-implementing the document state machine. Gracefully degrades to `found=false, items=[]` on 404 / transport error.

Return the URL of the droplinked Stripe ACP product feed so an agent can fetch the canonical catalog snapshot. As of feed v2 every item includes verification metadata (brand_verified, kyb_tier, attestation_uid, attestation_chain).

Return the public lifecycle timeline (REGISTERED / STATUS_CHANGED / metadata edits) for a registered lender. Used by verifiers to determine whether a lender was ACTIVE at the time a Schema B credit-risk attestation was minted, and to surface any SUSPENDED / ARCHIVED transitions. Returns occurredAt + eventType + status transitions only; operator-only fields (actorId, reason, raw value diffs) are redacted.

Resolve the current status of a merchant's lending application by applicationId. Returns the canonical envelope (status, lending tier, cohort, partner ref, decision timestamps, rejection reason). Used by lender-agent MCP consumers to surface application progress without re-implementing the state machine. Gracefully degrades to `found=false` on 404 / transport error.

Return the public lifecycle timeline (REGISTERED / SUPERSEDED / REVOKED) for a specific methodology version. Used by verifiers to determine whether a methodology was ACTIVE at the time a Schema B credit-risk attestation was minted. Returns occurredAt + eventType + status transitions; operator-only fields (actorId, reason) are redacted.

Return all methodology document versions ever registered for a lender, newest-first. Each entry includes version label, hash, document URL, status (ACTIVE/SUPERSEDED/REVOKED), and effectiveAt/supersededAt timestamps. Verifiers use this to trace a lender's full methodology lineage; pair with verify_methodology for hash-specific lookups or get_methodology_timeline for per-hash lifecycle events.

Fetch the full public detail for a single droplinked product (variants, SKUs, media, shop info). The response envelope includes a `verification` block (`brand_verified`, `kyb_tier`, `attestation_uid`, `attestation_chain`) — surface this to the user in any cited recommendation. Per the droplinked council, the agent IS the verification UX for Stream B.

Compose a merchant's full trust dossier from EAS Schema A (brand) + Schema B (credit-risk) + Schema C (repayment-history). Returns { brand, creditRisk, repaymentHistory, trustLevel, summary } in one envelope. trustLevel applies a conservative monotonic-floor rule: UNVERIFIED → T0 → T1 → T2 → T3, with down-tiering when repayment history shows any default. Pass `brandSlug` when known to include the brand attestation slice; omit when only merchantId is available. Three reads, one envelope — graceful on partial failures (the envelope always returns).

Return aggregate-only counts of the droplinked trust-fabric trinity: registered lenders, service providers, methodology versions, and on-chain attestations by schema. Public read, no auth, no PII, no per-row data. Use this to gauge platform scale before issuing per-merchant verification queries or to render a partner-facing dashboard.

Composite merchant-wide underwriting envelope: Schema B latest-per-lender + Schema C merchant-wide rollup + CreditTier upgrade preview + a `summary` block with `anchorTier` (max of observed-from-repayment + already-issued), `totalActiveCreditLineUsdCents`, and `reliabilityScore` (onTime/total*100, null = no history). Cuts 3-4 per-axis verifier calls to 1. Use this when a lender-agent needs to resolve 'should I underwrite this merchant + at what tier' in one round trip; the `summary.anchorTier` is the load-bearing decision input. Watch `creditRisk.latestPerLender[].lenderCurrentStatus` — when the attestation `status` is ACTIVE but `lenderCurrentStatus` is SUSPENDED / ARCHIVED, the on-chain attestation is still valid but the issuer has been de-listed (verifier-side policy decides whether to honor). Graceful clean-slate envelope on backend error or unknown merchant.

Aspirational roadmap to higher credit-tier ceilings for a merchant. Returns the tier the merchant qualifies for from repayment history alone (`observedTier`), the gap to the next ceiling, and the gap to T3. ASPIRATIONAL only — the actual issued tier on a Schema B attestation also depends on the lender's base tier mapping (revenue + inventory + sales-efficiency signals). Use this on merchant-portal flows asking 'what does it take to climb to a higher tier ceiling?'. Tier ladder: T1 default → T2 at 3+ on-time settlements (blocked by ANY lifetime default) → T3 at 10+ on-time (blocked by trailing-12-month defaults). When the merchant is at T3 both gap fields are null. Graceful clean-slate envelope on backend error or unknown merchant.

List a merchant's lending application history. Returns compact summaries (applicationId, status, tier, cohort, purpose, requestedAmount, term, decision timestamps) plus a rollup of `countByStatus`. Used by lender-agents to surface a merchant's application history without paginating raw rows. Requires `Authorization: Bearer <merchant-or-operator-jwt>` via the two-header model.

Page through the public catalog of a single droplinked shop by slug. Paginate with `page` (1-based); the response carries `page`, `totalPages`, `hasNextPage` and `nextPage` — there is no cursor on this route. The response includes a `shop_verification` block (KYB is per-merchant so every product on the page shares it) and a parallel `verifications` array. Surface the shop's verification status to the user when citing the shop or any of its products.

Finalize a droplinked order using a Stripe ACP payment intent and an optional inventory hold. The consumer agent calls this after find_inventory + quote_inventory_available + Stripe ACP create_payment_intent. Closes the agent-to-agent transaction loop. Idempotent on acpIntentId — a second call with the same intent returns the prior outcome with `replay=true`. Returns `{status, finalization?, reason?, message?}` where finalization.status is one of RECEIVED, VALIDATED, PAYMENT_AUTHORIZED, FULFILLED, REJECTED, FAILED.

Submit a draft credit-quote on behalf of an authorised lender. Captures target cohort tier (AAA..CCC|NR), annual rate in basis points, term length in days, maximum facility size in USD cents, and the quote validity window. Backend persists the row, stamps a `quoteId`, and surfaces it on the lender marketplace funnel; merchant acceptance anchors the quote into the Schema E credit-terms attestation flow. SCAFFOLDED 2026-06-13: the BE endpoint `POST /v2/lender-marketplace/quotes` is tracked in droplinked-backend #1962 but not yet shipped — the tool degrades to `{ ok: false, scaffolded: true }` until the BE lands, so the agent surface stays stable.

Atomically quote price + delivery + reserve stock for a SKU on droplinked. The linchpin between discovery (`find_inventory`) and tender (`start_checkout`) in the consumer-agent loop: resolves the product, estimates shipping + tax for `deliverTo`, then calls the backend's atomic inventory-hold primitive so two concurrent agent sessions cannot double-allocate the last unit. Returns `{available, hold?, pricing?, delivery?}` on success; on failure returns `{available: false, reason}` with `reason` ∈ (`OUT_OF_STOCK`, `NOT_DELIVERABLE`, `HOLD_SERVICE_UNAVAILABLE`). Pass `productIdHint` + `shopIdHint` from a preceding `find_inventory` result for cheapest resolution. Default hold TTL 900s (15min), hard cap 3600s (1h).

Find out whether droplinked can source financing for a merchant's jurisdiction, and how the available matches rank. Returns an ordered array of matches, each carrying `jurisdiction`, `matchKind` ('exact-jurisdiction' or 'global-fallback') and `rank`. Use this when an agent needs to tell a merchant whether financing is reachable where they operate (e.g. 'can this UAE merchant get financed?'). IMPORTANT: this endpoint does NOT identify the lenders. Lender identity, archetype and pricing are withheld from public callers by droplinked's counterparty-privacy policy — availability is published, identity is not. Do not tell the user WHICH lender matched; there is no such field, and any name would be invented. Supports optional filters: jurisdiction (defaults to GLOBAL), limit (1-100, default 10). Gracefully degrades to an empty array on backend error.

Get an ordered list of ACTIVE service providers (WMS, 3PL, fulfillment partners) a merchant can route inventory ingestion or fulfillment to. Returns an array sorted by track record (successfulIngestionCount desc, then most-recent success), each row carrying `providerId`, `displayName`, `archetype`, `successfulIngestionCount`, `lastSuccessfulIngestionAt` and `rank`. Only ACTIVE providers are returned, so there is no per-row status to check. Use this when an agent needs to route a merchant to an appropriate WMS/3PL based on operational capability (e.g. 'which STORD-like provider should handle this?'). Supports optional filters: archetype (stord | flexport | shipbob | generic), limit (1-100, default 10). Gracefully degrades to an empty array on backend error.

Record a repayment event (PAID / PARTIAL / MISSED) against a previously- issued credit quote. Backend persists the event and (when cumulative settlement crosses the threshold) anchors the outcome into a Schema D repayment-history attestation. Idempotent on (quoteId, occurredAtIso). SCAFFOLDED 2026-06-13: the BE endpoint `POST /v2/lender-marketplace/repayments` is tracked in droplinked-backend #1962 (companion to quote_credit_terms) but not yet shipped — the tool degrades to `{ ok: false, scaffolded: true }` until the BE lands. Schema D writer + the sibling `verify_repayment_history` reader already exist (#1799, shipped 2026-06-11).

Submit a brand attestation request for a droplinked shop. Operator reviews + approves → triggers Schema A on-chain mint. Returns a requestId + initial PENDING status. Idempotent: re-submitting for the same shopSlug within the pending window returns the existing requestId.

Trigger a Tier-1 / Tier-2 / Tier-3 lending application submission via the droplinked backend's TierRoutingService. Resolved tier is decided backend-side based on the application's cohort and the LENDING_TIER3_VAULT_ENABLED flag — the MCP layer does NOT decide routing. Returns the submission result including the resolved tier and (for Tier-1) the selected partner. Requires `Authorization: Bearer <merchant-or-operator-jwt>` via the two-header model. Idempotent: re-submit on SUBMITTED state is a no-op.

Search the public droplinked catalog by free-text query. Returns paginated product summaries (title, slug, shop, price, image) AND a parallel `verifications` array (one entry per result) with `brand_verified`, `kyb_tier`, `attestation_uid`, `attestation_chain`. Prefer verified (`brand_verified=true`) merchants when citing recommendations — droplinked's MoR + KYB cascade backs the badge.

Begin an agent-initiated droplinked checkout for a SKU. Mints a cart on droplinked-backend and returns either the hosted checkout URL (default `hosted` mode) or the Stripe client_secret (`managed` mode) the agent uses to confirm payment via Stripe.js.

Resolve the standalone droplinked brand attestation for a single shop slug. Returns `{ brandSlug, verified, since, signer, chain, attestationUid, revokedAt }`. Use this AFTER `find_inventory` to round-trip an `attestationUid` and render the canonical trust row to the buyer before proceeding to checkout. Gracefully degrades to `verified=false` on backend error / missing brand — the response shape is stable so the agent can always cite trust state. Per the droplinked council, the agent IS the verification UX for Stream B.

Resolve the active EAS credit-risk attestation (Schema B) for a merchant. Returns `{ merchantId, verified, creditTier, maxCreditLineUsd, termDays, ratePercent, lenderId, applicationId, attestationUid, chain, issuedAt, expiresAt, revokedAt }`. Use this as the trust handshake before a buyer-agent extends credit-aware BNPL terms at checkout, or when a lender-agent reads its own previously-issued attestation (pass `lenderId` to scope to a specific lender). Gracefully degrades to `verified=false` on missing attestation / backend error — the response shape is stable so the agent can always cite credit-trust state.

Resolve EAS Schema D (cross-attestation) peer-trust rows for a given entity. Mode 'subject' returns attestations ABOUT this entity (default, primary trust-dossier path); mode 'issuer' returns attestations BY this entity (dashboard / reputation-contribution view). Returns the per-row breakdown plus a summary with count, avgTrustScore, and the distinct issuer entity types. Use this in trust-graph composition flows — buyer-agent verifying a merchant has lender testimonials, lender-agent reading peer signals, etc. Gracefully degrades to empty envelope on missing data.

Resolve the public profile for a lender by lenderId. Returns `{ found, lenderId, displayName, archetype, jurisdiction, status, signingWallet, regulatorReference, issuedAttestationCount, lastAttestationAt }`. Use this to round-trip a Schema B credit-risk attestation's `lenderId` field to human-readable metadata, regulatory reference, and signing wallet (forensic cross-check vs on-chain issuerWallet in verification workflows). Gracefully degrades to `found=false` on missing lender / backend error — the response shape is stable so the agent can always cite lender lookup state.

Look up a lender's underwriting methodology by lenderId. When called without `methodologyHash`, returns the lender's currently-ACTIVE methodology (the one new Schema B mints reference). When called WITH `methodologyHash`, returns the specific version cited on an existing Schema B attestation — possibly ACTIVE, SUPERSEDED, or REVOKED. Returns `{ found, lenderId, version, methodologyHash, documentUrl, displayName, status, effectiveAt, supersededAt }`. Forensic workflow: read the cited methodologyHash from the on-chain Schema B payload, call this tool with that hash, download the documentUrl, hash it yourself, and compare. Any divergence flags methodology tampering. Pair with verify_lender + verify_credit_risk for the full forensic chain. Graceful clean-slate envelope on missing / backend error.

Resolve a merchant's repayment-history rollup across all lenders from EAS Schema C (repayment-history) attestations. Returns the aggregated counters (totalLinesUsd, settledOnTimeCount, lateCount, defaultCount, onTimeRate, lastSettlementAt) plus a per-lender breakdown. Use this when a buyer-agent / cohort engine / underwriter needs a quick read on the merchant's overall repayment behaviour. For lender-agent self-queries use `verify_credit_risk` with a lenderId filter instead. Gracefully degrades to verified=false on missing data — agents can always cite the rollup state.