# 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 (locked)

- Model: `residual_only` — residual = retail − wholesale. No ladder commission on store orders.
- Buyer pays **full retail** in crypto to Clickoor / D3AL wallets (platform-collect).
- Platform keeps wholesale (live catalog). Residual credits affiliate claim balance after the order is verified/activated.
- Retail must be ≥ wholesale and ≤ wholesale × 20.
- 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.
- `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.
- `partner_whoami` (Bearer `ckptr_`; no required args): Return the authenticated partner handle, scopes, and claim balance.
- `partner_catalog` (Bearer `ckptr_`; no required args): List resellable products/plans with wholesale floor, min/max retail (max 20×), and residual model notes.
- `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.
- `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 must be >= wholesale and <= 20× wholesale. Residual = retail − wholesale credits affiliate balance after paid.
- `partner_list_orders` (Bearer `ckptr_`; no required args): List recent orders on your book including fingerprint_id, IP, and device_type (no locker secrets).
- `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.
- `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**.
3. `POST /v2-api.php?action=partner_submit_order`
   `{ "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.

## 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)