# 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 and fixed answer price unless they already delegated spending authority.
- Use `palate_list_channels` before adding an optional query channel scope.
- Submit the paid query with the same user-visible question 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 supports user API keys and on-chain payment proof. Without an API key, payment proof is the access control.

Quotes advertise supported rails:

- `tempo` for MPP Tempo USDC.
- `x402_base` for x402 over Base USDC.

The quote response returns the selected rail, fixed answer price, payment nonce, receiver, and expiry. Payment proof is sent to `POST /api/palates/<slug>/query`.

Agent payments are non-refundable in v1.

The V1 agent quote returns a fixed answer price and a nonce for the selected payment rail.

## Query Responses

- Prefer concise synthesis with citations for human-facing answers.
- 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

Do not assume retries are free. If payment proof has already been spent or expired, get a fresh quote before retrying the paid query.

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

{
  "rail": "x402_base"
}
```

Query:

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

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

MCP tools:

- `palate_list_channels()`
- `palate_quote(rail)`
- `palate_query(question, 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": {
      "rail": "x402_base"
    }
  }
}
```