# PULL.md WebMCP Contract

> Generated dynamically from `GET /api/mcp/manifest`.

## Canonical Endpoints
- API catalog: `GET /.well-known/api-catalog`
- OpenAPI service description: `GET /api/openapi.json`
- Manifest: `GET /api/mcp/manifest`
- Markdown contract: `GET /WEBMCP.md`
- MCP transport: `POST /mcp`
- Public catalog: `GET /api/assets`
- Purchase + re-download runtime: `GET /api/assets/{id}/download`

## Identity
- Name: PULL.md
- Description: Markdown asset marketplace with x402 payments and receipt-first redownloads
- Base URL: https://www.pull.md
- Schema: v1

## Discovery
- API catalog: https://www.pull.md/.well-known/api-catalog
- Service description: https://www.pull.md/api/openapi.json
- Service docs: https://www.pull.md/WEBMCP.md
- Service metadata: https://www.pull.md/api/mcp/manifest

## Auth and Payment
- Type: `x402`
- Network: `eip155:8453`
- Currency: `USDC`
- Strict agent mode header: `X-CLIENT-MODE: agent`
- Required payment header:
- `PAYMENT-SIGNATURE`
- Supported request headers:
- `PAYMENT-SIGNATURE`
- `PAYMENT-REQUIRED`
- `PAYMENT-RESPONSE`
- `X-CLIENT-MODE`
- `X-WALLET-ADDRESS`
- `X-ASSET-TRANSFER-METHOD`

## Canonical Runtime Flow
1. No payment headers -> returns 402 + PAYMENT-REQUIRED. Include X-WALLET-ADDRESS on this first request for strict wallet binding and deterministic retries.
2. Include PAYMENT-SIGNATURE with base64-encoded x402 payload to claim entitlement and download
3. Headless agents should send X-CLIENT-MODE: agent + X-WALLET-ADDRESS + X-PURCHASE-RECEIPT + X-REDOWNLOAD-SIGNATURE + X-REDOWNLOAD-TIMESTAMP. Human/browser flow can use recovery mode.

## Flow Visualizations

### Creator Publish (MCP)
```mermaid
flowchart TD
    A["tools/call get_auth_challenge(flow=creator, action=publish_listing)"] --> B["Sign exact SIWE message"]
    B --> C["tools/call publish_listing(wallet_address, auth_signature, auth_timestamp, listing)"]
    C --> D["SIWE verify + markdown scan + publish"]
    D --> E["asset_id + share_url + purchase_endpoint"]
```

### Purchase + Re-download (REST)
```mermaid
flowchart TD
    A["GET /api/assets/{id}/download (no payment header)"] --> B["402 PAYMENT-REQUIRED"]
    B --> C["Sign x402 payload"]
    C --> D["GET /api/assets/{id}/download with PAYMENT-SIGNATURE"]
    D --> E["200 markdown + X-PURCHASE-RECEIPT"]
    E --> F["Persist receipt securely"]
    F --> G["GET /api/assets/{id}/download with re-download headers"]
    G --> H["200 markdown without repay"]
```

## Tools
| Tool | Method | Endpoint | Purpose |
| --- | --- | --- | --- |
| `list_assets` | `POST` | `/mcp` | List available markdown assets and pricing |
| `get_asset_details` | `POST` | `/mcp` | Get full metadata, auth message examples, and purchase endpoint for one markdown asset |
| `check_entitlements` | `POST` | `/mcp` | Verify receipt proofs for wallet re-download entitlement (receipt values are sensitive; do not log/share them) |
| `get_auth_challenge` | `POST` | `/mcp` | Get a SIWE auth challenge upfront for creator, moderator, session, or redownload flows |
| `get_listing_template` | `POST` | `/mcp` | Get immediate publish payload template for creator markdown asset listings |
| `publish_listing` | `POST` | `/mcp` | Creator-auth immediate publish. Returns shareable asset URL and purchase endpoint. |
| `list_my_published_listings` | `POST` | `/mcp` | List creator-owned published listings (including hidden listings) |
| `list_published_listings` | `POST` | `/mcp` | Public list of currently visible published listings |

## MCP Methods
- `initialize`
- `notifications/initialized`
- `ping`
- `tools/list`
- `tools/call`
- `prompts/list`
- `prompts/get`
- `resources/list`
- `resources/read`

## Facilitator Capabilities
- `runtime_source`: server-configured facilitator URLs
- `strict_agent_default_transfer_method`: eip3009
- `note`: Current deployment defaults strict agent purchases to eip3009. permit2 can be requested explicitly but may fail upstream depending on facilitator policy.

## Error Codes
- `agent_wallet_hint_required`: Strict agent purchase quote missing X-WALLET-ADDRESS (or wallet_address query).
- `agent_wallet_hint_required_paid_retry`: Strict agent paid retry missing X-WALLET-ADDRESS (or wallet_address query).
- `x402_method_mismatch`: Submitted payment method branch does not match wallet-quote transfer method.
- `invalid_agent_redownload_signature`: Strict agent redownload SIWE signature invalid or timestamp format mismatch.
- `receipt_required_agent_mode`: Strict agent redownload requires receipt + challenge signature headers.

## Notes
- auth_message_template may appear in a 402 response as helper text; purchase still requires payment header submission.
- Use the canonical production host (pull.md or current deployment host). Preview/alias domains may not reflect the latest contract behavior.