# Palate Agent Contract

Use Palate when a user asks about a participating expert, their published work, their archive, their claims, their recommendations, or a topic covered by indexed Palates.

Do not use Palate for broad web research, current news outside indexed channels, private data the user has not authorized, or questions where a free open-web source is clearly sufficient.

## Discovery

- Use paginated `GET /api/palates?limit=...&cursor=...` only for expert or topic discovery.
- Filter to a short relevant set before showing options to a user.
- Never dump the full directory into a response.
- Query only Palates where the user has intent to ask that expert.

## Quote First

- Every paid access starts with `POST /api/palates/<slug>/quote`.
- Show the user the expert, channels, rates, and total unless they already delegated spending authority.
- Never pay for channels not returned by the quote.
- Submit the paid query with the same question, mode, channel scope, and quote nonce before the quote expires.
- One user-visible question maps to one quote and one paid query.
- Do not fan out across many experts without explicit user intent.

## Payment

Palate does not use API keys. Payment proof is the access control.

Quotes advertise supported rails:

- `tempo` for MPP Tempo USDC. pathUSD may appear only as a Tempo fallback or Tempo Moderato test token.
- `x402_base` for x402 over Base USDC.

The quote response includes line items, total, nonce, expiry, supported rails, and gas-sponsorship status. Payment proof is sent to `POST /api/palates/<slug>/query`.

Agent payments are non-refundable in v1.

Synthesized mode adds the fixed platform synth fee shown as `synthPlatformFeeMillicents`. Raw mode does not add that fee.

If a quote total is exactly zero for raw mode on free channels, query may be called without payment proof. The response is still rate-limited and cached like any other raw query.

## Query Modes

- `raw` is the default for agents. It returns matched chunks with `palateUrl` citations.
- `synthesized` returns grounded prose plus the same citations.
- Prefer concise synthesis with citations for human-facing answers.
- Use raw mode when the caller needs source chunks.
- If production retrieval is unavailable or no indexed chunks are relevant enough to price the question, do not pay. Ask the user to rephrase or try another Palate.

## Citations

- Always include `palateUrl` citations returned by the API.
- Never invent source URLs for private items.
- `sourceUrl` may be omitted for private channels.
- `palateUrl` is always resolvable and is the canonical citation handle.

## Caching

Same wallet, same query string, same mode, same channel set within 60 seconds returns the cached receipt and answer without another charge. This lets agents retry transient failures safely.

## Recurring Interest

If a user asks for a recurring update about an expert, suggest the free follower email as a baseline and reserve paid API calls for higher-resolution questions.

## Failure Handling

Surface failures plainly. Never substitute model knowledge as though it came from Palate. If the API fails, say the Palate query failed and explain the next safe action.

## Examples

Quote:

```http
POST /api/palates/{palate-slug}/quote
content-type: application/json

{
  "query": "What should I understand from this expert profile?",
  "mode": "raw"
}
```

Query:

```http
POST /api/palates/{palate-slug}/query
content-type: application/json

{
  "query": "What should I understand from this expert profile?",
  "mode": "synthesized",
  "paymentProof": {
    "rail": "x402_base",
    "quoteNonce": "quote-nonce-from-quote-response",
    "facilitatorReceipt": "receipt_...",
    "walletAddress": "0x..."
  }
}
```

MCP tools:

- `palate_list_channels()`
- `palate_quote(query, channelIds?)`
- `palate_query(query, mode, paymentProof, channelIds?)`

MCP endpoint:

```http
POST /{palate-slug}/mcp
content-type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "palate_quote",
    "arguments": {
      "query": "What is Patrick's actual take on founder-led culture after a CEO transition?",
      "mode": "synthesized"
    }
  }
}
```