# Cardamom Skills

> Cardano address intelligence for agents and developers.  
> Freshly ground on-chain data — pre-seasoned for machine consumption.

---

## Base URL

```
https://cardamom.live
```

## Machine-Readable Manifest

The full manifest as JSON, with Claude-compatible tool definitions you can drop directly into the Anthropic API or Agent SDK:

```
GET /api/skills
```

---

## Authentication

All public endpoints are **unauthenticated** and rate-limited. Include an API key for higher limits:

```
X-Api-Key: your_key_here
```

---

## Response Envelope

Every skill response uses this shape:

**Success**
```json
{
  "data": { },
  "meta": {
    "requestId": "uuid",
    "freshness": {
      "lastIndexedAt": "2026-05-28T12:00:00Z",
      "sourceProvider": "blockfrost",
      "coverage": "partial"
    },
    "warnings": []
  },
  "error": null
}
```

**Error**
```json
{
  "data": null,
  "meta": { "requestId": "uuid" },
  "error": { "code": "ADDRESS_INVALID", "message": "..." }
}
```

**Error codes:** `ADDRESS_INVALID` · `ADDRESS_NOT_FOUND` · `PROVIDER_UNAVAILABLE` · `RATE_LIMITED` · `UNAUTHORIZED` · `NOT_FOUND` · `VALIDATION_ERROR` · `INTERNAL_ERROR` · `AI_GUARDRAIL` · `AI_UNAVAILABLE`

---

## Skills

### 1. search_address

Index a Cardano address and return wallet overview, statistics, and recent DeFi activity. Call this first for any new address or when you need fresh data.

```
POST /api/addresses/search
Content-Type: application/json

{
  "address": "addr1qy...",
  "forceRefresh": false
}
```

**Response data includes:** `address`, `addressId`, `addressType`, `network`, `snapshot`, `stats`, `recentActivity`, `cached`

Position queries are live and may depend on external protocol APIs. If a protocol position query does not finish, Cardamom may show the last known position snapshot with a warning rather than incorrectly erasing the position.

---

### 2. get_address

Return cached address overview without triggering re-indexing.

```
GET /api/addresses/{address}
```

Returns 404 when the address has not been indexed yet.

---

### 3. get_stats

Return the latest wallet statistics snapshot.

```
GET /api/addresses/{address}/stats
```

**Stats include:** ADA balance · token holdings · tx counts · DeFi counts · active positions · risk flags

---

### 4. get_activity

Return paginated, filterable DeFi activity.

```
GET /api/addresses/{address}/activity
  ?protocol=sundaeswap
  &action=swap
  &dateFrom=2026-01-01T00:00:00Z
  &dateTo=2026-05-28T23:59:59Z
  &page=1
  &pageSize=20
```

**Query params:** `protocol` · `action` · `dateFrom` · `dateTo` · `page` · `pageSize`

**Supported actions:** `swap` · `add_liquidity` · `remove_liquidity` · `stake` · `unstake` · `borrow` · `repay` · `lend` · `withdraw` · `open_cdp` · `add_collateral` · `mint` · `burn` · `liquidation` · `claim_reward` · `asset_movement` · `unknown_protocol_interaction`

Pagination is applied after duplicate protocol rows for the same transaction are collapsed, so `pagination.total` and `pagination.totalPages` describe the de-duplicated activity trail. `asset` and `minAmount` filters are reserved for future expansion.

---

### 5. get_leaderboard

Return public Cardamom leaderboard rankings.

```
GET /api/leaderboard
```

**Sections include:**

- `most-flavourful` — blended score from protocol variety, DeFi activity, fees, transactions, and open positions.
- `biggest-cauldron` — largest priced open DeFi position value, normalised to ADA where prices are available.
- `protocol-pantry` — most distinct supported DeFi protocols used.
- `fee-furnace` — most ADA spent on indexed supported DeFi activity fees.
- `spiciest-trail` — most supported DeFi activity rows.
- `busy-grinder` — most total transactions in the latest wallet snapshot.

Open-position values are conservative. ADA and known stablecoins can be priced; unsupported native assets are labelled as partial.

---

### 6. get_summary / generate_summary

**GET** returns the most recent AI summary (null if none exists).  
**POST** generates a new summary from indexed on-chain data.

```
GET  /api/addresses/{address}/summary
POST /api/addresses/{address}/summary
```

Summary includes: wallet behaviour overview · DeFi history · notable assets · risk signals · data freshness.

---

### 7. chat

Ask a natural-language question about an address.

```
POST /api/addresses/{address}/chat
Content-Type: application/json

{
  "message": "Which protocol does this address use most?",
  "conversationId": "optional-uuid-to-continue-a-conversation"
}
```

Answers are grounded in indexed on-chain data. Returns `reply`, `replies` (chunked), `conversationId`, and `guardrailTriggered`.

---

### 8. validate_address

Validate a Cardano address before passing it to other skills.

```
POST /api/addresses/validate
Content-Type: application/json

{ "address": "addr1qy..." }
```

Returns: `address` (normalised) · `type` (enterprise/base/stake) · `network` (mainnet/testnet) · `isValid`

---

## Protocol Skills

Each supported protocol has a unified skill endpoint that returns all intelligence for that protocol and address in a **single call**: filtered activity, live positions, yield stats.

The address is **auto-indexed** when not yet cached — no need to call search_address first.

```
GET /api/skills/{protocol}?address={cardano_address}&page=1&pageSize=20
```

**Supported protocols:**

| Protocol | Category | Positions |
|---|---|---|
| [`sundaeswap`](https://sundaeswap.finance) | DEX | ✓ |
| [`minswap`](https://minswap.org) | DEX | ✓ |
| [`fluidtoken`](https://fluidtokens.com) | Lending | ✓ |
| [`indigo`](https://indigoprotocol.io) | CDP / Synthetics | ✓ |
| [`liqwid`](https://liqwid.finance) | Lending | ✓ |
| [`dano`](https://dano.finance) | DEX + Lending | — |
| [`surflend`](https://surflending.org) | Lending | — |

**Example:**
```
GET /api/skills/sundaeswap?address=addr1qy...
```

**Response data includes:** `protocol` · `activities` (filtered) · `positions` · `yieldStats` · `hasPositions` · `pagination`

Without an address param, the endpoint returns the protocol's skill definition and metadata.

---

## Integration Suggestions

Anyone — human or agent — can request a new protocol integration.

```
POST /api/integration-suggestions
Content-Type: application/json

{
  "protocolName": "WingRiders",
  "website": "https://app.wingriders.com",
  "category": "dex",
  "reason": "WingRiders is one of the largest DEXes on Cardano by TVL."
}
```

**Fields:** `protocolName` (required) · `website` · `category` · `reason` (required, min 10 chars) · `contactInfo`

Protocol teams implementing their own adapters should follow the **Integration Standard:**
```
https://cardamom.live/protocol-standard
```

---

## Quick-start (Claude Agent SDK)

```typescript
import Anthropic from "@anthropic-ai/sdk";

// Fetch skills manifest
const manifest = await fetch("https://cardamom.live/api/skills").then(r => r.json());
const tools = manifest.data.tools;

// Use tools with Claude
const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  tools,
  messages: [{
    role: "user",
    content: "Summarize DeFi activity for addr1qy..."
  }]
});
```

When Claude calls a Cardamom tool, route it to the corresponding HTTP endpoint using the `http` field in each tool definition.

---

## Freshness and Coverage

All intelligence endpoints return `freshness` metadata:

- **`lastIndexedAt`** — when this address was last indexed
- **`sourceProvider`** — the on-chain data provider used (e.g. `blockfrost`)
- **`coverage`** — `partial` (searched-address indexing) · `full` · `unavailable`

Data is refreshed on-demand when a search is triggered and the cached data is older than 10 minutes.

## Explorer Links

Cardamom UI linkouts use AdaStat for addresses and transactions:

- `https://adastat.net/addresses/{address}`
- `https://adastat.net/transactions/{tx_hash}`

Agents should still use API responses as the source of truth and treat explorer URLs as human-readable references.

---

*Cardamom — Carda-mom knows best.*  
*Integration standard → https://cardamom.live/protocol-standard*