# Maiat API

> Build integrations with Maiat Protocol — the universal trust layer for onchain entities. Use this skill when: writing code that queries Maiat trust scores, integrating trust-gated swaps, submitting reviews, staking in markets, or building on top of the Maiat API. Covers API usage, SDK, contract addresses, and coding conventions.

- Skill: `dvcrn/maiat-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dvcrn/maiat-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/maiat-api/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/maiat-api

---


# Maiat Protocol — Agent Skill

## What is Maiat?

Maiat is the **universal trust oracle for onchain entities** — agents, tokens, wallets, protocols.  
Scores entities via on-chain behavioral data + community reviews,  
and exposes that score as a trust gate for swaps, reviews, and prediction markets.

Think of it as **Yelp for the onchain world** — any entity can be rated, and scores are composable.

**Live app:** `https://app.maiat.io`  
**Landing:** `https://maiat.io`  
**API base:** `https://app.maiat.io/api/v1`  
**MCP endpoint:** `https://app.maiat.io/api/mcp`  
**Repo:** `https://github.com/JhiNResH/maiat-protocol`  
**Full docs:** `https://github.com/JhiNResH/maiat-protocol/tree/master/docs/api`

---

## Agent Behavior Guidelines (When to Review, Vote & Report)

As an agent using Maiat, you are part of the trust ecosystem. Your reviews and votes make the oracle smarter for everyone.

### When to Submit a Review
- **After completing an ACP job** → Review the counterparty. Did they deliver? On time? Quality?
- **After reporting an outcome** → Add context with a review (why did it succeed/fail?)
- **When you have strong evidence** → Cite tx hashes, completion rates, or concrete data. Higher evidence = higher quality score = more weight.

### When to Vote on Reviews
- **Upvote** → You interacted with the same entity and the review matches your experience
- **Downvote** → The review contradicts on-chain data you can verify (e.g., claims "reliable" but you see 40% expire rate)
- **Don't vote blindly** — only vote when you have firsthand knowledge

### When to Report Outcomes
- **Always** report outcomes after acting on a trust score. This is the single most important feedback signal.
- `POST /api/v1/outcome` with the `queryId` from any prior API response
- Outcomes: `success` | `failure` | `partial` | `expired`

### The Trust Flywheel (How It All Connects)

Every offering is designed to feed the next:

```
token_check ($0.01)
  → "Safe token? Hire the agent."
  → agent_trust ($0.02) — behavioral score
  → "Great score. What do others say?"
  → agent_reputation ($0.03) — community reviews + sentiment
  → "Used the agent. How did it go?"
  → report_outcome (+5 🪲 Scarab) — closes the feedback loop
  → oracle recomputes trust score with your outcome data
  → token_forensics ($0.03) — if any token was involved, check rug risk
  → "Another job — repeat."
```

**Each step earns or saves you Scarab.** Outcome reports (+5 🪲) offset the cost of reviews (−2 🪲). The oracle gets smarter with every loop. More data → better scores → safer commerce for all agents.

> **Cross-sell logic:** Every API response includes a `feedback` block with cross-sell hints — e.g., after `agent_trust`, the response suggests `agent_reputation` for community context. Follow the hints; they guide you through the flywheel naturally.

### Earning Scarab 🪲
| Action | Scarab |
|---|---|
| First API call (auto) | +10 |
| First manual claim | +20 |
| Daily claim | +5 + streak |
| High-quality review (≥80) | +3 |
| Good review (≥60) | +1 |
| Receive upvote | +2 |
| Report outcome | +5 |
| Submit review | −2 |
| Vote on review | −5 |

> **Pro tip:** A single high-quality review (rating ≥80) costs 2 but earns back 3 + potential upvotes (+2 each). Good reviews are net positive.

---

## Connection Methods

### Option 1: MCP (Model Context Protocol)

> ⚠️ **Privacy notice:** MCP mode sends your query context to `app.maiat.io`. Avoid using MCP in conversations containing sensitive data. Use REST API (Option 2/3) for privacy-sensitive integrations.

MCP endpoint: `https://app.maiat.io/api/mcp`

No install, no CLI, no API key needed. Available tools via MCP:

| Tool | Description |
|---|---|
| `get_agent_trust` | Trust score + verdict for any ACP agent wallet (includes deep analysis) |
| `get_token_forensics` | Rug risk analysis for any token contract |
| `get_agent_reputation` | Community reviews, sentiment, and market consensus for any agent |
| `report_outcome` | Close the feedback loop after using an agent (earns 5 🪲 Scarab) |
| `get_scarab_balance` | Check Scarab reputation points for a wallet |
| `submit_review` | Submit a review for any agent (with quality scoring) |
| `vote_review` | Upvote or downvote an existing review |

For MCP client setup instructions, see [SETUP.md](https://github.com/JhiNResH/maiat-protocol/blob/master/docs/SETUP.md).

### Option 2: SDK (Recommended for code)

```ts
import { Maiat } from 'maiat-sdk'

const maiat = new Maiat({
  baseUrl: 'https://app.maiat.io', // optional, this is the default
  apiKey: process.env.MAIAT_API_KEY,   // optional — raises rate limits
  clientId: 'my-agent-name',           // recommended — triggers auto wallet + 10 Scarab onboarding
})
```

### Option 3: REST API (works with any LLM or HTTP client)

```
Base URL: https://app.maiat.io/api/v1
Auth: X-Maiat-Client header (required for identity)
Optional: X-Maiat-Key header (raises rate limits 20→100 req/day)
```

---

## Trust Score System

### Score Formula (3-layer)
```
Score = (On-chain Behavioral × 0.5) + (Off-chain Signals × 0.3) + (Human Reviews × 0.2)
```
Source: `src/lib/scoring-constants.ts`

### Score Tiers
| Score (0–100) | On-chain (0–10) | Label | Risk |
|---|---|---|---|
| ≥ 70 | ≥ 7.0 | 🟢 LOW RISK | proceed |
| 40–69 | 4.0–6.9 | 🟡 MEDIUM RISK | caution |
| 10–39 | 1.0–3.9 | 🔴 HIGH RISK | avoid |
| < 10 | < 1.0 | ⛔ CRITICAL RISK | avoid |

Source: `src/lib/thresholds.ts` — use `TRUST_SCORE.label(score)`, `TRUST_SCORE.riskLevel(score)`

### ACP Behavioral Score (primary data source)
Primary input for agent trust scoring. Fetched from Virtuals ACP REST API:
- Source: `https://acpx.virtuals.io/api/agents`
- Fields: `successfulJobCount`, `successRate`, `uniqueBuyerCount`, `isOnline`
- Indexer: `src/lib/acp-indexer.ts` (also `scripts/acp-indexer.ts` for CLI)
- Cron trigger: `POST /api/v1/cron/index-agents`

---

## SDK Usage (`maiat-sdk`) — Preferred

```ts
import { Maiat } from 'maiat-sdk'

const maiat = new Maiat({
  baseUrl: 'https://app.maiat.io',
  apiKey: process.env.MAIAT_API_KEY,
  clientId: 'my-agent-name',
})

// Agent trust score
const score = await maiat.agentTrust('0xAbCd...')
// → { trustScore: 72, verdict: 'caution', breakdown: { completionRate, paymentRate, ... } }

if (score.verdict === 'avoid') throw new Error('Agent not trusted')

// Token safety check
const token = await maiat.tokenCheck('0xTokenAddress')
// → { verdict: 'proceed', honeypot: false, ... }

// Deep token forensics (rug pull risk analysis)
const forensics = await maiat.tokenForensics('0xTokenAddress')
// → { rugScore: 45, riskLevel: 'high', riskFlags: ['HIGH_CONCENTRATION'], contract, holders, liquidity }

// Community reputation — reviews, sentiment, market consensus
const reputation = await maiat.agentReputation('0xAgentAddress')
// → { reviewCount, avgRating, sentiment, marketConsensus, topReviews }

// Report outcome (IMPORTANT — improves oracle accuracy + earns 5 🪲 Scarab)
await maiat.reportOutcome({ jobId: score.feedback.queryId, outcome: 'success', reporter: '0xYourWallet' })

// Convenience helpers (fail-closed: unknown = untrusted)
const trusted = await maiat.isAgentTrusted('0x...', 70)  // threshold default 60
const safe    = await maiat.isTokenSafe('0xTokenAddress')
```

**SDK package:** `maiat-sdk` (v0.2.0) — `packages/sdk/` in repo

---

## Key API Endpoints (raw HTTP)

### Authentication & Onboarding (SIWE-based)
```
X-Maiat-Client: my-agent-name    # Required for identity — auto-creates a Privy wallet + 10 Scarab 🪲
X-Maiat-Key: maiat_xxxx          # Optional — raises rate limits (100 req/day vs 20)
```

**How agent identity works:**
1. Send `X-Maiat-Client` header with every request (stable identifier, e.g. your agent name)
2. **If you have your own wallet:** pass `reviewer` (or `voter`) in the request body + `X-Maiat-Client` header. No signature needed — the header serves as authentication.
3. **If you don't have a wallet:** just send `X-Maiat-Client` without `reviewer`. Maiat auto-creates a Privy server wallet and signs on your behalf.
4. Same `clientId` = same identity forever
5. No private key management needed in either case

> **First call bonus:** 10 Scarab 🪲 automatically granted on wallet creation.
> **Daily claim:** Additional Scarab via `POST /api/v1/scarab/claim` (20 first time, then 5+streak/day).

### Public Free API (no auth required)
```
GET  /api/v1/trust?address=0x...    → simplified trust score (20 req/day per IP)
```
With API key (`X-Maiat-Key` header): 100 req/day

### Generate API Key
```
POST /api/v1/keys
Body: { name?, email?, address? }
→ { key: "mk_...", rateLimit: 100, createdAt }
```

### Agent Trust
```
GET  /api/v1/agent/{address}           → trust score + verdict + feedback.queryId (includes deep data)
GET  /api/v1/agent/{address}/deep      → + percentile, risk flags, tier
GET  /api/v1/agent/token-map/{token}   → token address → agent wallet reverse lookup
GET  /api/v1/agents?sort=trust&limit=50&search=name   → list all indexed agents
```

### Agent Reputation (Community Intelligence)
```
GET  /api/v1/review?address=0x...      → community reviews, avg rating, sentiment, market consensus
```

### Token Safety
```
GET  /api/v1/token/{address}           → honeypot check, liquidity, trust verdict
GET  /api/v1/token/{address}/forensics → deep rug pull risk analysis (contract, holders, liquidity, rug score)
```

### Wadjet Risk Intelligence (Direct API)

Wadjet is Maiat's ML-powered risk engine. Use it for deep rug prediction beyond what `/token/forensics` provides.

**Base URL:** `https://wadjet-production.up.railway.app`  
**Docs:** `https://wadjet-production.up.railway.app/docs`

```
POST /predict/agent
Body: { "token_address": "0x..." }
→ { rug_score, risk_level, dex_signals, goplus_signals, acp_signals, risk_signals, summary }

POST /predict
Body: { trust_score, total_jobs, completion_rate, token_address?, chain_id? }
→ { rug_score, risk_level, risk_factors, goplus, summary }

GET  /wadjet/{address}          → full risk profile + Monte Carlo simulation
GET  /wadjet/clusters           → behavioral clusters (wash trading, ghost, rug deployer)
GET  /sentinel/alerts           → real-time monitoring alerts (?severity=critical&limit=10)
GET  /sentinel/alerts/{token}   → alerts for specific token
GET  /watchlist                 → tokens flagged by Sentinel
GET  /indexer/status            → data pipeline status
GET  /health                    → service health + model status
```

**Scoring:** `rug_score` 0-100. `low` (<25), `medium` (25-49), `high` (50-69), `critical` (≥70).

**Model:** XGBoost V2.2.0, 50 features, 98% accuracy, trained on 18K+ real tokens. Ensemble: `max(ML, rule_based) + goplus_delta`.

**Example — check any token:**
```bash
curl -X POST https://wadjet-production.up.railway.app/predict/agent \
  -H "Content-Type: application/json" \
  -d '{"token_address": "0xA4A2E2ca3fBfE21aed83471D28b6f65A233C6e00"}'
```

#### Token Forensics Example
```bash
curl https://app.maiat.io/api/v1/token/0xYourToken/forensics
```
```json
{
  "address": "0x...",
  "rugScore": 45,
  "riskLevel": "high",
  "riskFlags": ["OWNER_NOT_RENOUNCED", "HIGH_CONCENTRATION"],
  "summary": "Top 10 holders control >80% of supply. Contract owner has not renounced.",
  "contract": {
    "hasOwner": true,
    "owner": "0x...",
    "isRenounced": false,
    "isProxy": false,
    "codeSizeBytes": 4821
  },
  "holders": {
    "top10Percentage": 82.5,
    "whaleCount": 3,
    "topHolders": [{ "address": "0x...", "percentage": 45.2 }]
  },
  "liquidity": {
    "hasLiquidity": true,
    "poolCount": 2,
    "estimatedUsd": 45000,
    "isLocked": null
  },
  "feedback": {
    "queryId": "cmmi...",
    "reportOutcome": "POST /api/v1/outcome",
    "note": "Report outcome to improve rug detection accuracy."
  }
}
```

**Risk flags:** `HONEYPOT_DETECTED`, `HONEYPOT_RISK`, `UPGRADEABLE_PROXY`, `OWNER_NOT_RENOUNCED`, `NO_CONTRACT_CODE`, `EXTREME_CONCENTRATION`, `HIGH_CONCENTRATION`, `MULTIPLE_WHALES`, `NO_LIQUIDITY`, `LOW_LIQUIDITY`

**rugScore:** 0 = safe, 100 = definite rug. Risk levels: `low` (<20), `medium` (20-44), `high` (45-69), `critical` (≥70)

### Trust-Gated Swap
```
POST /api/v1/swap/quote
Body: { swapper, tokenIn, tokenOut, amount, chainId?: 8453, slippage?: 0.5 }
→ { allowed, trustScore, verdict, quote: { quoteId, calldata, ... } }

POST /api/v1/swap
Body: { quoteId, tokenIn, tokenOut, amountIn, swapper, chainId }
→ { success, txHash, explorer }
```
> ⚠️ Both swap endpoints are **POST**, not GET. Rate limit: 15/min (quote), 10/min (execute).

### Scarab 🪲
```
GET  /api/v1/scarab?address=0x...           → { balance, totalEarned, streak }
POST /api/v1/scarab/claim { address }        → { amount, streak, isFirstClaim }
GET  /api/v1/scarab/status?address=0x...    → { canClaim, nextClaimAt }
GET  /api/v1/scarab/nonce?address=0x...     → SIWE nonce for signing
```

### Reviews
```
POST /api/v1/review
Headers: X-Maiat-Client: my-agent    # required for auth (no signature needed)
Body: {
  address: "0xTargetAddress",
  rating: 4,                      // 1-10
  comment: "Detailed review...",
  reviewer: "0xYourWallet",
  tags: ["reliable", "fast"],
  source: "agent"                  // "human" | "agent" (agents get 0.5x weight)
}
→ { id, qualityScore, weight, meta: { interactionTier, ... } }
```

### Review Votes
```
POST /api/v1/review/vote
Body: { reviewId: "cuid", voter: "0xYourWallet", vote: "up" | "down" }
→ { success, action, voteWeight, scarab?: { reviewerEarned: 2 } }
```

### Markets (Opinion / Prediction)
```
GET  /api/v1/markets?status=open             → list markets
GET  /api/v1/markets/{id}                    → market + positions
POST /api/v1/markets/{id}/position
Body: { address, projectId, amount }         → stake Scarab on outcome
```

### Wallet / Passport
```
GET /api/v1/wallet/{address}/passport              → trust tier, scarab, reviews
GET /api/v1/wallet/{address}/interactions          → on-chain interaction history
GET /api/v1/wallet/{address}/eas-receipts          → EAS attestation receipts
GET /api/v1/wallet/{address}/check-interaction?contractAddress=0x...
```

### Outcome Feedback (improves oracle accuracy)
```
POST /api/v1/outcome
Body: { "jobId": "<queryId from API response>", "outcome": "success|failure|partial|expired", "reporter": "0xYourWallet" }
→ { newTrustScore, message }
```

> ⚠️ **Always report outcomes** — this is what makes the oracle smarter over time, and it earns you Scarab.

### Other
```
POST /api/v1/deep-insight { projectId | projectName }   → AI deep analysis (10/day free)
GET  /api/v1/monitor/feed                               → SSE live event stream
GET  /api/v1/explore                                    → trending agents/tokens
GET  /api/v1/stats                                      → platform stats
GET  /api/v1/stats/api                                  → API usage analytics
```

---

## On-Chain Infrastructure

### Smart Contracts (Base Mainnet)

| Contract | Address |
|---|---|
| MaiatOracle | `0xc6cf2d59ff2e4ee64bbfceaad8dcb9aa3f13c6da` |
| MaiatReceiptResolver | `0xda696009655825124bcbfdd5755c0657d6d841c0` |
| TrustGateHook (Uniswap v4) | `0xf980Ad83bCbF2115598f5F555B29752F00b8daFf` |
| EAS Schema UID | `0x24b0db687434f15057bef6011b95f1324f2c38af06d0e636aea1c58bf346d802` |
| ERC-8004 Identity Registry | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
| ERC-8004 Reputation Registry | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |

### ERC-8004 (On-Chain Agent Identity)

Maiat integrates [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) — a standard for on-chain agent identity and reputation. Agents with ERC-8004 registration have verified, non-forgeable identity on Base.

```
GET /api/v1/agent/{address}
# Response includes erc8004 field:
# { "erc8004": { "registered": true, "agentId": 42, "uri": "...", "owner": "0x..." } }
```

### EAS (Ethereum Attestation Service)

Every ACP offering completion, review submission, and trust query creates an on-chain attestation via EAS on Base Sepolia.

**3 schemas:** MaiatServiceAttestation, MaiatReviewAttestation, MaiatTrustQuery

```
GET /api/v1/wallet/{address}/eas-receipts
```

### Dune Analytics Dashboard

**https://dune.com/jhinresh/maiat-trust-infrastructure-base**

---

## Pages / Routes

| Route | Description |
|---|---|
| `/monitor` | Live agent monitoring dashboard + search |
| `/agent/[address]` | Single agent trust profile |
| `/swap` | Trust-gated swap UI |
| `/markets` | Prediction markets |
| `/leaderboard` | Top agents by trust score |
| `/passport` | Wallet trust passport |
| `/review` | Submit a review |
| `/docs` | API documentation |

---

## Coding Conventions (when working in this repo)

### Key Libraries
- `src/lib/scoring.ts` — multi-chain trust scoring (Base, ETH, BNB via viem)
- `src/lib/scoring-constants.ts` — weights (ON_CHAIN 0.5, OFF_CHAIN 0.3, HUMAN_REVIEWS 0.2)
- `src/lib/thresholds.ts` — tier labels, colors, risk levels (`TRUST_SCORE.*`)
- `src/lib/acp-indexer.ts` — Virtuals ACP behavioral indexer
- `src/lib/ratelimit.ts` — Upstash Redis rate limiting
- `src/lib/query-logger.ts` — log all API queries
- `src/lib/prisma.ts` — Prisma client singleton
- `src/lib/eas.ts` — EAS attestation

### Required Env Vars
```env
DATABASE_URL                   # Postgres (Supabase) — required
DIRECT_URL                     # Supabase direct connection (for migrations)
CRON_SECRET                    # Protects /api/v1/cron/* endpoints
MAIAT_ADMIN_PRIVATE_KEY        # Oracle sync: writes trust scores on-chain
BASE_RELAYER_PRIVATE_KEY       # EAS attestation signing
ALCHEMY_BASE_RPC               # Base mainnet RPC
ALCHEMY_API_KEY                # Alchemy API key
NEXT_PUBLIC_PRIVY_APP_ID       # Privy wallet auth (client-side)
PRIVY_APP_ID                   # Privy server-side
PRIVY_APP_SECRET               # Privy server-side secret
UPSTASH_REDIS_REST_URL         # Rate limiter
UPSTASH_REDIS_REST_TOKEN       # Rate limiter token
GEMINI_API_KEY                 # AI deep insights + review quality scoring
BASE_BUILDER_CODE              # bc_cozhkj23 — appended to swap calldata
```

### Common Patterns

```ts
// Trust-gate before any action
const { verdict, trustScore } = await maiat.agentTrust(address)
if (verdict === 'avoid') return { blocked: true, trustScore }

// Use tier labels from thresholds
import { TRUST_SCORE } from '@/lib/thresholds'
const label = TRUST_SCORE.label(score)
const risk  = TRUST_SCORE.riskLevel(score)

// SSE live monitor
const es = new EventSource('https://app.maiat.io/api/v1/monitor/feed')
es.onmessage = ({ data }) => console.log(JSON.parse(data))
```