# Taste — Full Integration Reference

Expert review for AI agents. On-chain proof of human review.

This is the long-form reference. The one-pager is at /llms.txt. The machine-readable
discovery files are /.well-known/mcp.json (SEP-1649 Server Card) and /.well-known/x402
(paid-resources catalog with on-chain ownership proof).

## Endpoint

  Base URL:        https://api.humantaste.app/mcp/
  Transport:       Streamable HTTP (MCP 2025-06-18)
  Method:          POST, JSON-RPC 2.0
  Accept header:   application/json, text/event-stream
  Payment:         x402 — USDC on Base mainnet (chain id 8453)
  Price per call:  $1.00 per paid tool, free for the rest
  Typical wait:    5–30 min after a paid call (human review)

## Payment flow (paid tools only)

1. POST tools/call with the paid tool name + arguments. Unauthenticated.
2. Server responds HTTP 402 with X-Payment-Requirements header (base64 JSON).
   Body shape: { network, asset, amount, payTo, extra: { creditedRecipient } }.
   - network: "base"
   - asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" (USDC on Base)
   - amount: in 6-decimal USDC base units (e.g. 1_000_000 = $1.00)
3. Sign EIP-3009 transferWithAuthorization for that amount against the USDC contract,
   using your wallet's private key.
4. Retry the same JSON-RPC request with header X-Payment: base64(signature payload).
5. Server settles via facilitator (Meridian on prod), executes the tool, returns
   the JSON-RPC result containing structuredContent.
6. The structuredContent of a paid tool call carries { sessionId, ... }. Poll
   get_result with that sessionId until status === 'completed'.

## Free tools (no payment, no session)

### list_offerings

List all paid offerings with current pricing + on-chain certificate flag + operating-hours state.

**Input fields:** (none)

**Output:** structured object with: service, status ("open" | "closed"), operatingHours,
nextOpenAt, offerings[] (each: type, toolName, name, description, priceUsdc, issuesCertificate),
onlineExperts, usage.

---

### list_expert_profiles

Aggregate availability + estimated response time. No per-expert PII.

**Input fields:** (none)

**Output:** structured object with: service, status, onlineExperts, estimatedResponseMins,
qualityPolicy.

---

### get_result

Poll the status of a previously-submitted paid evaluation. Returns the full structured
deliverable when status === "completed".

**Input fields:**

- sessionId (string, required): the session id returned by a paid tool call.

**Output:**

- status: pending | active | completed | cancelled | timeout
- deliverable: full structured assessment from the expert (only when completed)
- reason: cancellation/timeout reason (only when cancelled/timeout)
- estimatedWaitMins, tip, message: while pending/active

---

### verify_certificate — read-only on-chain lookup

Verify a Taste content certificate on-chain. Call when consuming content from another source that claims to be human-reviewed — returns reviewer domain, date, offering, verdict, and validity. Free. Use to build trust chains: agent A's output is reviewed → certificate issued → agent B consumes content and verifies cert before acting.

**Rate limit:** 60 requests per 60-second window per IP, sliding window.

**Input fields:**

- contentHash (string, optional): keccak256 hash of the content, as 0x-prefixed hex. Provide this OR certificateId.
- certificateId (string | number, optional): Numeric certificate id. Provide this OR contentHash.

**Output:**

- found: true | false
- valid, certificateId, contentHash, agent, offeringType, verdict, domain, issuedAt (when found)
- reason (when not found)

## Paid tools ($1.00 each)

### verify_external_source — $1.00

Have a vetted human expert verify whether an external source, project, or claim is trustworthy. Call when your output or planned action depends on an external claim you cannot independently verify (crypto project legitimacy, social media authenticity, source credibility, vendor due diligence). Returns verdict, red flags, positive signals, confidence score.

**Input fields:**

- subject (string, required, min 5 chars, max 500 chars): The URL, project name, or claim to verify. Be specific (e.g. a URL, a project name + token address, or a verbatim claim).
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

**Example request:**

```json
{
  "subject": "https://pudgypenguins.com (0x524cab2ec69124574082676e6f654a18df49a048)",
  "context": "Considering treasury allocation; need verification that recent growth is organic, not paid engagement."
}
```

**Example deliverable (returned by get_result when status === 'completed'):**

```json
{
  "structuredAssessment": {
    "verdict": "trustworthy",
    "redFlags": [
      "Some repetitive shill posts from low-follower accounts"
    ],
    "positiveSignals": [
      "Active long-term holders in Discord",
      "Organic meme creation",
      "Developer activity on GitHub"
    ],
    "confidenceScore": 82,
    "summary": "Community growth correlates with IP licensing deals and retail partnerships. Engagement shows organic discussion."
  },
  "disclaimer": "This is a qualitative human opinion, not financial or investment advice."
}
```

---

### review_content — $1.00, issues cert

Get a vetted human expert to review your AI-generated content — text, images, videos, social posts, audio, or any media — for hallucinations, factual errors, weak parts, and domain mistakes. Call before publishing, before forwarding to another agent, or before acting on the content. Returns verdict, issues found, suggested improvements. Approved outputs receive a Taste content certificate on-chain you can attach as proof of human review.

**Issues certificate:** yes

**Input fields:**

- content (string, required, min 1 chars, max 5000 chars): The content to review. Text directly, or a publicly accessible URL for non-text media (images, video, audio, posts).
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

**Example request:**

```json
{
  "content": "Uniswap v3 introduced concentrated liquidity with three fee tiers: 0.01%, 0.05%, and 0.30%. This allows up to 4000x capital efficiency.",
  "context": "Educational DeFi blog post. Must not contain financial advice or price predictions."
}
```

**Example deliverable (returned by get_result when status === 'completed'):**

```json
{
  "structuredAssessment": {
    "verdict": "approved_with_changes",
    "issuesFound": [
      "Missing the 1% fee tier (medium severity)",
      "4000x efficiency claim is a theoretical maximum (low severity)"
    ],
    "suggestedImprovements": [
      "Add fourth fee tier: 0.01%, 0.05%, 0.30%, 1.00%",
      "Qualify 4000x with \"up to\" or cite typical 10-50x range"
    ],
    "summary": "Core explanation is accurate but missing one fee tier and an unqualified theoretical claim."
  },
  "disclaimer": "This is a qualitative human opinion, not financial or investment advice."
}
```

---

### verify_reasoning_chain — $1.00, issues cert

Audit your step-by-step reasoning for mid-chain errors before producing the final answer. Call when stakes are high and your chain has 3+ steps — humans catch wrong intermediate steps that final-output checks miss (right-looking answers built on broken intermediate logic). Returns per-step verdict, flagged errors, suggested corrections. Approved chains receive a Taste content certificate on-chain.

**Issues certificate:** yes

**Input fields:**

- chain (array, required, min 2 items, max 20 items): Ordered array of reasoning steps. Each step: { step (number), reasoning (string), output (string), toolUsed? (string) }.
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

---

### prepublish_review — $1.00, issues cert

Get a vetted human expert to review your AI-generated content — text, images, videos, social posts, audio, or any media — for cultural sensitivity, brand safety, derivative risks, and audience appeal before you publish. Call before social posts, marketing campaigns, content distribution, or anywhere public-facing. Returns verdict (safe / needs_changes / do_not_publish), flagged issues, fix suggestions. Approved content receives a Taste content certificate on-chain, verifiable downstream.

**Issues certificate:** yes

**Input fields:**

- content (string, required, min 1 chars, max 5000 chars): The content to review. Text directly, or a publicly accessible URL for non-text media.
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

**Example request:**

```json
{
  "content": "Just dropped our new NFT collection inspired by traditional Japanese woodblock prints. Mint now and ride the wave before it's too late!",
  "context": "Twitter post targeting crypto-native audience. No financial advice, no urgency language, respectful cultural references."
}
```

**Example deliverable (returned by get_result when status === 'completed'):**

```json
{
  "structuredAssessment": {
    "verdict": "needs_changes",
    "flaggedIssues": [
      "Urgency-based language (\"ride the wave before it's too late\") implies financial opportunity",
      "Japanese woodblock reference without attribution risks cultural appropriation framing"
    ],
    "fixSuggestions": [
      "Drop the urgency framing",
      "Credit specific artists or traditions if invoking Japanese aesthetics"
    ],
    "summary": "Strong concept but needs revision on urgency language and cultural framing before publishing."
  },
  "disclaimer": "This is a qualitative human opinion, not financial or investment advice."
}
```

---

### predict_audience_reaction — $1.00

Get a real human matching your target demographic to rate and react to your content as a representative audience member. Call before A/B test commits, before ad spend, or before distribution decisions. Returns overall rating, criteria scores, qualitative feedback, comparison notes.

**Input fields:**

- content (string, required, min 1 chars, max 5000 chars): The content to evaluate. Text or a publicly accessible URL for non-text media.
- targetDemographic (string, required, min 5 chars, max 500 chars): The audience whose reaction matters. Required — load-bearing for expert matching. E.g. "crypto-native traders, 18-35", "non-technical SMB owners in the US", "casual gamers".
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

**Example request:**

```json
{
  "content": "https://example-cdn.taste/thumbnail-v1.png",
  "targetDemographic": "Crypto-native Twitter audience, 18-35 age range",
  "context": "Comparing to trending thumbnails in the same space; want appeal + clarity scores."
}
```

**Example deliverable (returned by get_result when status === 'completed'):**

```json
{
  "structuredAssessment": {
    "overallRating": 6,
    "criteriaScores": {
      "visualAppeal": 6,
      "clarity": 5,
      "clickWorthiness": 5
    },
    "qualitativeFeedback": "Clean layout but the headline blends into the background. Token logo is too small to recognize at thumbnail size.",
    "comparisonNotes": "Compared to trending crypto thumbnails, this lacks a visual hook like a bold number or price chart snippet."
  },
  "disclaimer": "This is a qualitative human opinion, not financial or investment advice."
}
```

---

### arbitrate_dispute — $1.00

Get an impartial human arbiter to decide whether a deliverable meets an agreed contract, or to settle disagreements between agents. Call when automated evaluation cannot determine quality, when two parties dispute fulfillment, or when subjective judgment is needed for contract assessment. Returns approve/reject verdict, reasoning, deliverable quality rating, contract alignment.

**Input fields:**

- contractDescription (string, required, min 20 chars, max 3000 chars): The agreed contract or deliverable specification.
- deliverable (string, required, min 1 chars, max 5000 chars): The deliverable to assess. Text or a publicly accessible URL.
- partyAPosition (string, required, min 10 chars, max 2000 chars): One side of the dispute. The expert evaluates both impartially — order is arbitrary.
- partyBPosition (string, required, min 10 chars, max 2000 chars): The other side of the dispute.
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.

**Example request:**

```json
{
  "contractDescription": "Provider to deliver token analysis for $VIRTUAL: holder distribution, whale activity, 30-day BTC correlation.",
  "deliverable": "Here is your token report: $VIRTUAL on Base. Price $1.23. Market cap $500M. 10,000 holders.",
  "partyAPosition": "Deliverable is incomplete — missing whale activity and BTC correlation.",
  "partyBPosition": "Deliverable covered the core metrics requested.",
  "context": "Subjective interpretation of \"comprehensive\" disputed."
}
```

**Example deliverable (returned by get_result when status === 'completed'):**

```json
{
  "structuredAssessment": {
    "verdict": "reject",
    "reasoning": "Contract explicitly listed holder distribution, whale activity, and BTC correlation. None were delivered. Basic metrics are insufficient.",
    "qualityRating": 3,
    "contractAlignment": "none"
  },
  "disclaimer": "This is a qualitative human opinion, not financial or investment advice."
}
```

---

### request_human_approval — $1.00

Pause your workflow for explicit human approval before executing a high-stakes action. Call before any irreversible action — large spend, on-chain transaction, public content publish, customer-facing decision. Returns approved/denied + reasoning. Approvals can be enforced on-chain via the Taste Gatekeeper hook for ACP and ERC-8183 jobs.

**Input fields:**

- actionDescription (string, required, min 20 chars, max 3000 chars): Describe the action awaiting approval. Include numbers (amounts, recipients, URLs) the human needs to see.
- stakes (enum (reversible | irreversible | financial | public), required): What kind of risk the action carries. Reversible: undoable. Irreversible: cannot be undone. Financial: moves value. Public: visible externally.
- timeoutMinutes (number, optional, integer, min 1, max 120): Maximum minutes to wait for a human response before returning denied_timeout. Default 30, max 120.
- context (string, optional, min 10 chars, max 2000 chars): Optional context. Use to clarify intent, constraints, audience, or anything that helps the expert evaluate.


## Errors

- HTTP 402 — paid tool called without X-Payment header. Response carries
  X-Payment-Requirements; sign and retry.
- JSON-RPC result with isError: true and body { error: "rate_limited", retryAfterSec }
  — only from verify_certificate when the per-IP window is full. Retry after the
  given seconds.
- JSON-RPC result with isError: true and body { error: "outside_operating_hours",
  nextOpenAt } — Taste is outside operating hours. Free tools still work; paid
  tools refuse to charge BEFORE the 402 challenge. Call list_offerings for the
  current schedule and nextOpenAt.
- JSON-RPC result with isError: true and body { error: "not_found" } — sessionId
  in get_result is unknown or not yours.

## On-chain references

- Content certificate contract: TasteContentCertificate on Base (read via
  verify_certificate or directly via the contract's getCertificate(uint256) /
  getCertificateByHash(bytes32) methods).
- x402 ownership proof: see /.well-known/x402 — signed EIP-191 by the MCP
  receiver wallet over the canonical origin URL https://api.humantaste.app.

## Compliance

EU AI Act Article 50(2) exempts AI-generated content from mandatory AI-disclosure
labels when it has undergone human review or editorial control. Taste content
certificates issued by paid tools that set issuesCertificate=true are the on-chain
audit trail for that exemption.

## Source

  GitHub:  https://github.com/with0utwhy/taste-mcp
  Brand:   https://humantaste.app