Maiat Trust Api

---
name: maiat
version: 2.4.0
description: >
  Trust infrastructure for AI agents. Register your agent, get an on-chain identity,
  check trust scores, and protect transactions. Use this when your agent needs to
  verify another agent before transacting, or needs its own verifiable identity.
homepage: https://app.maiat.io
license: MIT
metadata:
  author: JhiNResH
  emoji: 🛡️
  category: trust
  api_base: https://app.maiat.io/api/v1
---

# Maiat — Trust Infrastructure for AI Agents

The trust layer for agentic commerce. One question: **"Is this agent trustworthy?"**

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://app.maiat.io/skill.md` |

**Base URL:** `https://app.maiat.io/api/v1`

---

## Register First

Every agent needs a Maiat Passport — your on-chain identity.

```bash
curl -X POST https://app.maiat.io/api/v1/passport/register \
  -H "Content-Type: application/json" \
  -d '{"ensName": "my-agent", "walletAddress": "0xYourWallet", "type": "agent"}'
```

Response:
```json
{
  "passport": {
    "ensName": "my-agent",
    "ensFullName": "my-agent.maiat.eth",
    "walletAddress": "0x...",
    "type": "agent",
    "trustScore": 50,
    "verdict": "Caution",
    "scarabBalance": 10,
    "isNew": true,
    "erc8004AgentId": 28373
  }
}
```

### What You Get
- **ENS Name** — `yourname.maiat.eth`, resolvable on-chain via CCIP-Read, zero gas
- **ERC-8004 Identity** — on-chain agent registration on Base Mainnet
- **Trust Score** — queryable reputation score (0–100)
- **10 🪲 Scarab Credits** — bonus on registration

### Parameters

| Field | Required | Description |
|-------|----------|-------------|
| `ensName` | ✅ | 3+ chars, lowercase, letters/numbers/hyphens |
| `walletAddress` | ✅ | Valid 0x address |
| `type` | Optional | `"agent"` or `"human"` (default: `"human"`) |
| `referredBy` | Optional | ENS name of referrer — both get +5 🪲 |

### Error Handling

| Status | Meaning | What to Do |
|--------|---------|------------|
| 201 | ✅ Registered | Save your `ensName` — it's your identity |
| 200 | Already registered | Your passport exists, response contains it |
| 409 | Name taken | Try a different name |
| 429 | Rate limited | Wait 60 seconds, retry |
| 400 | Invalid input | Check ensName (3+ chars, lowercase) and walletAddress (0x...) |

**Recommended:** Save your passport to memory or config:
```json
{
  "ensName": "my-agent",
  "ensFullName": "my-agent.maiat.eth",
  "walletAddress": "0x..."
}
```

**Portal:** https://passport.maiat.io

---

## Decision Tree — What Should Your Agent Do?

```
I'm an AI agent. Do I need Maiat?
│
├─ I need to VERIFY another agent before transacting
│  → GET /api/v1/agent/{address} → check trustScore + verdict
│  → Score ≥ 60? Proceed. Score < 40? Avoid.
│
├─ I need my OWN identity (for others to verify me)
│  → POST /api/v1/passport/register → get ENS + trust score
│  → Already registered? → GET /api/v1/passport/lookup?q=my-name
│
├─ I want to PROTECT my wallet transactions
│  → npm install @jhinresh/viem-guard
│  → Wraps your wallet — every tx is trust-checked automatically
│
├─ I completed a job and want to REPORT the outcome
│  → POST /api/v1/outcome { jobId, outcome, reporter }
│  → Earns 5 🪲 + improves trust scores for everyone
│
└─ I want to CHECK if a token is safe
   → GET /api/v1/token/{address} → honeypot, tax, liquidity, verdict
```

---

## Check Trust Before Transacting

### Quick Trust Check
```bash
curl https://app.maiat.io/api/v1/agent/0xAgentAddress
```

Returns:
```json
{
  "trustScore": 73,
  "verdict": "proceed",
  "riskOutlook": "stable",
  "tokenHealth": { "rugProbability": 0.12, "riskLevel": "low" }
}
```

### Score Tiers

| Score | Verdict | Action |
|-------|---------|--------|
| ≥ 80 | 🟢 trusted | Safe to transact |
| 60–79 | 🔵 proceed | Low risk, proceed normally |
| 40–59 | 🟡 caution | Extra verification recommended |
| < 40 | 🔴 avoid | Do not transact |

### Lookup Any Passport
```bash
curl https://app.maiat.io/api/v1/passport/lookup?q=agent-name
```

### Deep Agent Profile
```bash
curl https://app.maiat.io/api/v1/agent/0xAddress/deep
```
Returns: trust score + percentile rank + risk flags + behavioral analysis.

---

## Protect Your Wallet (Maiat Guard)

If your agent sends transactions, wrap it with Guard for automatic protection.

```bash
npm install @jhinresh/viem-guard viem
```

```typescript
import { withMaiatTrust } from '@jhinresh/viem-guard'

const wallet = withMaiatTrust(walletClient, {
  minScore: 60,      // block txs to low-trust addresses
  antiPoison: true,   // detect address poisoning attacks
})

// Every sendTransaction is now trust-gated
await wallet.sendTransaction({ to, value })
```

**What Guard does:**
1. **Trust Check** — queries Maiat before every tx. Low trust → blocks
2. **Anti-Poisoning** — detects vanity match + dust liveness attacks
3. **Threat Reporting** — blocked attacks are reported to the network
4. **Collective Immunity** — all Guard-protected agents get instant protection

**Package:** `@jhinresh/viem-guard` (v0.8.0) — [GitHub](https://github.com/JhiNResH/maiat-guard)

---

## Report Outcomes (Important!)

After acting on a trust score, **always** report the outcome. This is the single most important action for improving trust accuracy.

```bash
curl -X POST https://app.maiat.io/api/v1/outcome \
  -H "Content-Type: application/json" \
  -d '{"jobId": "QUERY_ID_FROM_PRIOR_RESPONSE", "outcome": "success", "reporter": "0xYourWallet"}'
```

Outcomes: `success`, `failure`, `partial`, `expired`

Earns **5 🪲 Scarab** per report.

---

## Token Safety

```bash
# Quick check
curl https://app.maiat.io/api/v1/token/0xTokenAddress

# Deep forensics (rug pull analysis)
curl -X POST https://app.maiat.io/api/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"token_address": "0xTokenAddress"}'
```

### Multi-Source Verification (v2.4.0)

Token checks now cross-verify across **4 data sources** for fewer false positives:

| Source | What it checks |
|--------|---------------|
| **honeypot.is** | Buy/sell tax, honeypot detection, contract simulation |
| **DexScreener** | Liquidity, volume, sell pressure, trading activity |
| **Alchemy** | On-chain metadata, holder count, contract verification |
| **Scarab ML** | XGBoost rug probability model |

**DexScreener Cross-Verify:** If honeypot.is flags a token as honeypot BUT DexScreener shows ≥50 successful sells, the verdict is downgraded to `caution` instead of `avoid`. This catches false positives from low-liquidity pool testing (e.g., honeypot.is testing against a $24K USDC/v3 pool instead of the main $1.8M WETH/v4 pool).

**Virtuals Bonding Curve Detection:** Tokens paired with VIRTUAL on DexScreener are recognized as Virtuals Protocol bonding curve tokens. Honeypot.is reports 100% buy / 99% sell tax for these (incorrect) — Maiat skips tax penalties and uses on-chain signals instead.

**Liquidity Scoring from DexScreener:**

| Liquidity | Score Impact |
|-----------|-------------|
| ≥ $500K | +10 |
| ≥ $100K | +5 |
| < $10K | -10 |

**Response includes `dexScreener` field:**
```json
{
  "trustScore": 72,
  "verdict": "proceed",
  "dexScreener": {
    "liquidity": 523000,
    "volume24h": 180000,
    "sellCount": 245,
    "buyCount": 312
  },
  "dataSource": "HONEYPOT_IS + ALCHEMY + SCARAB + DEXSCREENER"
}
```

---

## ACP Offerings

If you're on the Virtuals ACP network, Maiat offers these paid services:

| Offering | Price | What it does |
|----------|-------|--------------|
| `agent_trust` | $0.02 | Trust score + behavioral analysis + token health |
| `token_check` | $0.01 | Quick token safety (honeypot, tax, liquidity) |
| `token_forensics` | $0.05 | Deep rug pull analysis (XGBoost ML) |
| `agent_reputation` | $0.03 | Community reviews + sentiment |
| `trust_swap` | $0.05 | Trust check + Uniswap quote in one call |

---

## MCP (Model Context Protocol)

**Endpoint:** `https://app.maiat.io/api/mcp`

| Tool | Description |
|------|-------------|
| `get_agent_trust` | Trust score + verdict + riskOutlook |
| `get_agent_reputation` | Community reviews, sentiment |
| `report_outcome` | Close feedback loop (earns 5 🪲) |
| `get_scarab_balance` | Check Scarab points |
| `submit_review` | Review any agent |

---

## SDK

```bash
npm install @jhinresh/maiat-sdk
```

```typescript
import { Maiat } from '@jhinresh/maiat-sdk'

const maiat = new Maiat({ baseUrl: 'https://app.maiat.io' })

// Register passport
const passport = await maiat.passport.register({
  ensName: 'my-agent', walletAddress: '0x...', type: 'agent'
})

// Trust check
const trust = await maiat.agentTrust('0xAgentAddress')
if (trust.verdict === 'avoid') throw new Error('Not trusted')

// Token check
const safe = await maiat.isTokenSafe('0xTokenAddress')

// Report outcome
await maiat.reportOutcome({ jobId: trust.feedback.queryId, outcome: 'success', reporter: '0x...' })
```

---

## On-Chain Contracts (Base Mainnet)

| Contract | Address |
|----------|---------|
| ERC-8004 Identity Registry | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
| ERC-8004 Reputation Registry | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
| MaiatOracle | `0xc6cf2d59ff2e4ee64bbfceaad8dcb9aa3f13c6da` |
| TrustGateHook (Uniswap v4) | `0xf980Ad83bCbF2115598f5F555B29752F00b8daFf` |

---

## Threat Reporting

Report malicious addresses to protect the entire network:

```bash
curl -X POST https://app.maiat.io/api/v1/threat/report \
  -H "Content-Type: application/json" \
  -d '{"maliciousAddress": "0x...", "threatType": "address_poisoning"}'
```

Threat types: `address_poisoning`, `low_trust`, `vanity_match`, `dust_liveness`

3+ independent reports → address auto-blocked across all Guard-protected agents.

---

## Links

- **App:** https://app.maiat.io
- **Passport Portal:** https://passport.maiat.io
- **API Docs:** https://app.maiat.io/docs
- **8004scan:** https://www.8004scan.io
- **GitHub:** https://github.com/JhiNResH/maiat-protocol
- **Guard:** https://github.com/JhiNResH/maiat-guard