# D3AL Partner MCP

> Remote HTTP MCP for D3AL / Clickoor affiliates. An agent can onboard a handle, mint a `ckptr_` API key once, create residual mini-stores, set retail (wholesale <= price <= 20x wholesale), and export a storefront. Buyers pay D3AL wallets. You earn residual (retail - wholesale) in the affiliate claim balance. Fulfillment stays on Clickoor.

Marketplace shop (humans): https://d3al.xyz
Brand site: https://clickoor.com

## Connect

- [MCP endpoint](https://d3al.xyz/mcp): HTTPS JSON-RPC `initialize`, `tools/list`, `tools/call`, `ping`. Also `POST {"tool":"partner_docs"}`.
- [Human docs](https://d3al.xyz/mcp): designed HTML page (English / Chinese).
- [Machine JSON](https://d3al.xyz/mcp?format=json): tool defs + money rules + antifraud.
- [This file](https://d3al.xyz/mcp/llms.txt): agent summary (also https://d3al.xyz/llms-mcp.txt).
- [Marketplace llms.txt](https://d3al.xyz/llms.txt): shop / products, not partner tools.

Config after you have a key (never put `ckptr_` in public storefront JS):

```toml
[mcp_servers.d3al_partner]
url = "https://d3al.xyz/mcp"
headers = { Authorization = "Bearer ckptr_YOUR_KEY" }
```

## Onboard (no key yet)

Call public tool `partner_onboard` with:

- `handle` (required): 3–30 chars `a-z 0-9 _`
- `evm_address` (required): `0x` + 40 hex, BEP-20 USDT payout
- `referrer` (optional): parent affiliate handle
- `key_name` (optional): label, default `mcp-agent`

Creates the affiliate if new, or resumes if the EVM matches. Returns `ckptr_…` **once**. Save it, add the header above, then `partner_whoami`.

Same over HTTP (no CSRF): `POST https://d3al.xyz/v2-api.php?action=partner_onboard`

Website: https://d3al.xyz/affiliate/api (session) to create / list / revoke keys and set optional IP allowlists.

## Money

- Model: `residual_only` — every sale credits residual (retail − wholesale) + the referring affiliate's ladder commission into the claim balance. **Markup is optional**: set retail = wholesale to sell at cost and still earn the affiliate commission.
- Buyer pays **full retail** in crypto to Clickoor / D3AL wallets (platform-collect).
- Platform keeps wholesale (live catalog). Residual credits the partner claim balance after the order is verified/activated. Affiliate ladder commission posts to the referrer as on direct orders.
- Retail must be ≥ wholesale and ≤ wholesale × 20.
- Worked example: wholesale $6.00. Retail $9.00 → $3.00 residual + affiliate ladder cut per sale. Retail $6.00 (at cost) → you still earn the affiliate ladder cut on every sale.
- Content locker secrets are **never** returned to partner MCP/API.

## Tools

- `partner_docs` (public; no required args): Money rules, security notes, and how residual pricing works for reseller mini-stores.
  - Example `tools/call` arguments: `{}`
  - Example response: `{"money_model":"residual_only","max_markup_mult":20,"rules":[…]}`
- `partner_onboard` (public; required: handle, evm_address): Onboard as a D3AL affiliate from this agent (no browser). Pass a unique handle + your EVM payout address. Creates the affiliate if new, or resumes if the EVM matches. Returns a ckptr_ API key ONCE — save it in MCP config then call partner_whoami. Optional referrer handle.
  - Example `tools/call` arguments: `{"handle":"myshop","evm_address":"0x40Be1E7A25eE13Bcde7e2603C3A9eaA79e6dDd3E","key_name":"my-agent"}`
  - Example response: `{"ok":true,"api_key":"ckptr_xK9mQ2vLpT8wR4nJcF7s… (shown ONCE — save it)","handle":"myshop","affiliate_created":true,"next":"Add header Authorization: Bearer ckptr_… then call partner_whoami"}`
- `partner_whoami` (Bearer `ckptr_`; no required args): Return the authenticated partner handle, scopes, and claim balance.
  - Example `tools/call` arguments: `{}`
  - Example response: `{"ok":true,"handle":"myshop","scopes":["catalog:read","orders:read","balance:read","stores:write"],"stores":1,"evm_address":"0x40Be…"}`
- `partner_catalog` (Bearer `ckptr_`; no required args): List resellable products/plans with wholesale floor, min/max retail (max 20×), and residual model notes.
  - Example `tools/call` arguments: `{}`
  - Example response: `{"catalog":{"x_premium":{"product_label":"X Premium","plans":[{"plan_duration":"3 months","wholesale_usd":"6.00","min_retail_usd":"6.00","max_retail_usd":"120.00","money_model":"residual_only"}]}},"docs":{…}}`
- `partner_create_store` (Bearer `ckptr_`; no required args): Create a mini-store (slug + name). Returns store_url https://d3al.xyz/s/{slug} and publishable_id for public checkout.
  - Example `tools/call` arguments: `{"name":"My Shop","slug":"myshop"}`
  - Example response: `{"ok":true,"store":{"id":12,"slug":"myshop","publishable_id":"pb_7f3k…","status":"live","url":"https://d3al.xyz/s/myshop"}}`
- `partner_list_stores` (Bearer `ckptr_`; no required args): List stores owned by the partner, including offers.
- `partner_update_store` (Bearer `ckptr_`; required: store_id): Update store name, status (draft|live|suspended), or theme.
- `partner_upsert_offer` (Bearer `ckptr_`; required: store_id, product, plan_duration, retail_price_usd): Set retail price for a product/plan on a store. Retail can equal wholesale (sell at cost — you still earn the affiliate commission) up to 20× wholesale. Residual (retail − wholesale) + the affiliate ladder commission both credit after payment verifies.
  - Example `tools/call` arguments: `{"store_id":12,"product":"x_premium","plan_duration":"3 months","retail_price_usd":9.00,"active":true}`
  - Example response: `{"ok":true,"offer":{"store_id":12,"product":"x_premium","plan_duration":"3 months","retail_price_usd":"9.00","wholesale_usd":"6.00","residual_usd":"3.00","active":true},"message":"Offer saved. Residual $3.00 → your claim balance after payment verifies. Referring affiliate also earns ladder commission on each sale."}`
- `partner_list_orders` (Bearer `ckptr_`; no required args): List orders on your book: fingerprint_id, IP, device_type, commission + residual per order, plus a totals summary (revenue, affiliate commission, residual). Optional filters: status, product, plan_duration; paginate with limit/offset.
  - Example `tools/call` arguments: `{"status":"activated","limit":5,"offset":0}`
  - Example response: `{"orders":[{"id":4379,"product":"x_premium","username":"buyer1","plan_duration":"6 months","amount_paid":"12.00","status":"activated","referral_commission_usd":"1.20","partner_residual_usd":"6.00","created_at":"2026-09-06 08:00:00"}],"pagination":{"limit":5,"offset":0},"summary":{"total_orders":14,"revenue_usd":"168.00","affiliate_commission_usd":"16.80","partner_residual_usd":"84.00"}}`
- `partner_antifraud` (public; no required args): Required anti-fraud + first-party fingerprinting stack for MCP storefronts: 10-minute pay window, device/IP binding, tx-hash anti-snipe. Use this when building a custom storefront.
- `partner_order_signals` (Bearer `ckptr_`; required: order_id): Fraud signals for one of your orders: fingerprint, IP, device, plus your other orders that share the same fingerprint or IP.
- `partner_balance` (Bearer `ckptr_`; no required args): Affiliate claim balance including residual store earnings.
  - Example `tools/call` arguments: `{}`
  - Example response: `{"balance":{"handle":"myshop","claim_balance_usd":"84.00","lifetime_residual_usd":"84.00","paid_out_usd":"0.00"}}`
- `partner_get_storefront_snippet` (Bearer `ckptr_`; no required args): Return iframe snippet + hosted URL. Prefer partner_export_storefront to deploy a full separate site.
- `partner_export_storefront` (Bearer `ckptr_`; no required args): Export a standalone HTML storefront you can host on any domain (Netlify, Cloudflare Pages, GitHub Pages, VPS). Uses publishable_id only — never the API key. Includes 10-minute pay window + first-party fingerprint.

## Storefronts

- Hosted: `https://d3al.xyz/s/{slug}` after `partner_create_store`.
- Theme: `primary_color`, `accent_color`, `tagline`, `about`, `logo_url`, `telegram`, `x_handle`, `mode` (`auto`|`light`|`dark`).
- Export: `partner_export_storefront` → save `html` as `index.html` on any static host. Uses `publishable_id` only.

Public checkout (no API key, CORS open):

1. `POST /v2-api.php?action=partner_create_checkout_session`
   `{ "publishable_id", "product", "plan_duration", "username", "fingerprint_id", "accept_terms": true }`
2. Buyer pays **exact** retail USDT/USDC within **10 minutes**. Two payment modes: `payment_mode=direct` (default — pay `payment_addresses.evm`, then submit the tx hash in step 3) or `payment_mode=ctx` with `ctx_chain`/`ctx_token` (platform mints a unique-address invoice, confirms automatically, NO tx-hash submission).
3. `POST /v2-api.php?action=partner_submit_order` (direct mode only)
   `{ "claim_token", "tx_hash", "fingerprint_id", "accept_terms": true, "payment_source": "partner_store" }`

Products: `x_premium`, `telegram_premium`, `google_ai_pro`. Call `partner_catalog` for live plans and wholesale floors.

## Full checkout walkthrough (agent with a storefront)

```json
// 1. Create checkout session (public, no key). Two payment modes:
// POST https://d3al.xyz/v2-api.php?action=partner_create_checkout_session
{"publishable_id":"pb_7f3k…","product":"x_premium","plan_duration":"3 months","username":"buyer1","accept_terms":true,"payment_mode":"direct"}
// → {"checkout":{"claim_token":"a1b2…","amount_usd":"9.00","payment_addresses":{"evm":"0xf479…"},"ttl_seconds":600}}

// direct mode: buyer sends exactly 9.00 USDT to payment_addresses.evm within
// 10 minutes, then you submit the tx hash (step 3).

{"publishable_id":"pb_7f3k…","product":"x_premium","plan_duration":"3 months","username":"buyer1","accept_terms":true,"payment_mode":"ctx","ctx_chain":"base","ctx_token":"USDT"}
// → {"checkout":{"claim_token":"a1b2…","payment_mode":"ctx","ctx":{"invoice_id":"inv_…","payment_address":"<unique HD address>","expires_at":…}}}

// ctx mode: buyer pays the unique invoice address — confirmation is tracked
// automatically by the platform webhook and the order fulfils server-side.
// NO tx-hash submission needed. Pay window auto-extends for confirmations.

// 3. direct mode only — submit the tx hash (public, CORS open):
// POST https://d3al.xyz/v2-api.php?action=partner_submit_order
{"claim_token":"a1b2…","tx_hash":"0xabc…","fingerprint_id":"<same fingerprint as checkout>","accept_terms":true,"payment_source":"partner_store"}
// → {"ok":true,"order_id":4402}
```

Note: `fingerprint_id` is the SHA-256 device fingerprint generated in your storefront JS (see `partner_antifraud`). It must be identical at checkout-create and submit, or the order is rejected.

## Anti-fraud (required for custom storefronts)

Call `partner_antifraud` for the live field list. Same stack as d3al checkout:

- First-party fingerprint only (no FingerprintJS). SHA-256 of canvas / WebGL / audio / fonts / hardware.
- Reject empty / `unavailable` / `error` fingerprints.
- Submit fingerprint must match the payment intent.
- 10-minute pay window; claim token is hashed server-side.
- Do not reuse an old tx hash from before the session.

## Security notes for agents

- Auth header only. `?api_key=` is rejected (logs / Referer leak).
- Do not require extra encryption on `/mcp` — Cursor / Claude / Grok send plain JSON-RPC over HTTPS.
- A stolen `ckptr_` cannot create, list, or revoke sibling keys (panel session only).
- Optional REST HMAC (`X-Partner-Timestamp`, `X-Partner-Nonce`, `X-Partner-Signature`) is never required on `/mcp`.
- Never embed `ckptr_` in exported HTML or buyer-facing JS.

## Optional

- [Affiliate join](https://d3al.xyz/affiliate/join)
- [Affiliate API keys](https://d3al.xyz/affiliate/api)
- [Shop](https://d3al.xyz/shop)
- [Terms](https://d3al.xyz/terms)
- [Privacy](https://d3al.xyz/privacy)