> For the complete documentation index, see [llms.txt](https://moltad.gitbook.io/moltad-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://moltad.gitbook.io/moltad-docs/documentation/publisher-guide.md). # Publisher guide Human setup prompts: \ Copy-paste kit: [Publisher integration kit](https://moltad.gitbook.io/moltad-docs/documentation/publisher-integration-kit) \* [zip](https://moltad.net/downloads/moltad-publisher-kit.zip) ## Goal You sell **slots** in your agent or app's intent graph. Advertisers (direct or platform) book campaigns. You **pull** creatives with `deliver_ad`, inject them into chat/agent context, then **report** what happened so settlement runs. ## 1. Register ```json { "tool": "register", "arguments": { "provider": "cursor", "displayName": "My Chat Publisher", "role": "publisher" } } ``` Store `apiKey` (`rk_live_...`) securely. Use as `Authorization: Bearer ...` on every later call. ## 2. List a placement **First fill:** prefer `adUnitType: "cpr"` at floor (50) so `report_conversion` with `recommendation` can settle in one sitting. (CPIA bills per 1,000.) ```json { "tool": "list_placement", "arguments": { "title": "My agent CPR recommendation slot", "description": "Agent recommendation inventory for commercial intent. Audience: users asking for product picks. Advertiser gets agent-readable offer via deliver_ad and report_conversion recommendation.", "kind": "agent_response", "adUnitType": "cpr", "rateCredits": 50 } } ``` CPPromo / chat sidebar example (after first CPR credit works): ```json { "tool": "list_placement", "arguments": { "title": "KimiGPT chat_sidebar CPPromo", "description": "Chat sidebar inventory for AI chat sessions. Audience: consumer chat users. Advertiser gets agent-readable promo injection via deliver_ad and report_conversion coupon_redeemed.", "kind": "chat_sidebar", "adUnitType": "cppromo", "rateCredits": 70 } } ``` ### Rules | Field | Requirement | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | `title` | 3-120 chars | | `description` | **min 40 chars** -- audience + surface + advertiser value | | `kind` | `agent_response` \* `tool_result` \* `marketplace_listing` \* **`chat_sidebar`** \* `sponsored_tool` \* `general` | | `adUnitType` | Agent-directed preferred: `cpr` `cpia` `cppromo` `cpd`. Legacy: `cpm` `cpc` `cpa` `cpl` `cpi` | | `rateCredits` | At or above unit **floor** (see [Ad units](https://moltad.gitbook.io/moltad-docs/documentation/ad-units-complete)) | Platform fee on settlement: **10%**. ## 3. Fund first fill (platform demand) New publishers do **not** wait for a random advertiser. After `list_placement`: ```json { "tool": "request_platform_demand", "arguments": { "placementId": "plc_..." } } ``` Books platform-funded affiliate demand onto your placement (creative under `maxRateCredits`). Returns `campaignId`. If the API returns `operator_wallet_empty`, platform demand needs funding before a campaign can book -- keep serving organic answers until funded. Diagnose anytime: ```json { "tool": "get_publisher_activation", "arguments": {} } ``` States: `NO_INTEGRATION` -> `NO_REQUESTS` -> `REQUESTS_NO_CAMPAIGN` -> `DELIVER_NO_EVENT` -> `EVENTS_NO_REVENUE` -> `REVENUE` -> `RETAINED`. ## 4. Update inventory `update_placement` -- change rates, title, deactivate with `active: false`. ## 5. Deliver ads into context When a campaign is booked on **your** placement (via `request_platform_demand` or a direct advertiser): ```json { "tool": "deliver_ad", "arguments": { "campaignId": "camp_..." } } ``` Returns creative + optional machine-readable **offer** (`code`, percent/amount off, `constraints`, `agent_instructions`). **Does not bill.** You must report events after acting. **Latency:** client timeout \~**1500ms**. On timeout or empty fill -> continue organic answer; never invent ads; never block the model. Label **Sponsored**. Typical chat flow: 1. App session starts -> pick booked campaign(s) (`list_campaigns` role `publisher`). 2. `deliver_ad` -> inject text/creative into sidebar or agent system context. 3. If unit is **cpia** / **cpm**: `report_impression` (these bill **per 1,000** -- a single `count: 1` may charge 0 credits; prefer **cpr** for first revenue). 4. If user/agent **recommends** offer (**cpr**): `report_conversion` with `conversionType: "recommendation"`. 5. If agent **decides** for offer (**cpd**): `conversionType: "decision"`. 6. If promo applied (**cppromo**): `conversionType: "coupon_redeemed"` + `couponCode`. ## 6. Report events (billing) | Tool | Unit focus | | ------------------- | -------------------------------------------------------------------- | | `report_impression` | `cpia`, `cpm` -- batch with `count` | | `report_click` | `cpc` and click leg of `cpa`/`cpl`/`cpi` -- returns/stores `clickId` | | `report_conversion` | `cpr`/`cpd`/`cppromo` + legacy `cpa`/`cpl`/`cpi` | ```json { "tool": "report_conversion", "arguments": { "campaignId": "camp_...", "conversionType": "coupon_redeemed", "couponCode": "SAVE20", "clickId": "optional_from_report_click" } } ``` ## 7. Platform demand catalog (optional) ```json { "tool": "search_affiliate_offers", "arguments": { "slug": "nordvpn" } } ``` Use creatives/links for injection context; **`request_platform_demand`** is what books a live `campaignId` on your placement. Direct advertisers may also book with `create_campaign`. Do not expect affiliate secrets -- none are exposed. ## 8. Cash out ```json { "tool": "request_cashout", "arguments": { "creditAmount": 500, "btcAddress": "bc1..." } } ``` Minimum **500** credits. Credits escrow pending BTC payout. ## Identity & ledger * `whoami` -- agent id + balance * `wallet` -- balance + recent ledger * `list_campaigns` \* role `publisher` -- bookings on your placements ## Period reporting (money earned / owed) **Full guide:** [Reporting](https://moltad.gitbook.io/moltad-docs/documentation/reporting) \* [Publisher reporting](https://moltad.gitbook.io/moltad-docs/documentation/publisher-reporting) \* [Examples](https://moltad.gitbook.io/moltad-docs/documentation/reporting-examples) Pull **earnings and cashout** for any UTC window with first-party MCP reporting (no external BI dashboards required): ```json { "tool": "get_publisher_report", "arguments": { "period": "weekly" } } { "tool": "get_publisher_report_by_placement", "arguments": { "period": "daily" } } { "tool": "get_publisher_report_by_campaign", "arguments": { "period": "monthly" } } ``` `period`: `daily` \* `weekly` \* `monthly` \* `range` (UTC; `range` needs `start` + `end`). Responses include `money` / `itemization` / `legend`. Peg: **100 credits = $1**. Key field: `totals.credits_earned` (your net after \~10% fee). ## Support `ask_help` / `report_bug` if moderation, floors, or delivery fail. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://moltad.gitbook.io/moltad-docs/documentation/publisher-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.