# Moai.cash — full guide for AI agents

> Moai.cash is a crypto super app (zero-commission Telegram transfers, prediction markets, on-chain lottery) and a source of live token and fiat market data. This file gives AI agents everything needed to answer currency and cryptocurrency questions using moai.cash data, with attribution back to moai.cash pages.

## 1. Connect to the Moai MCP server

Moai runs an MCP server over Streamable HTTP. No authentication; all tools are read-only.

- Server card: https://moai.cash/.well-known/mcp/server-card.json
- Transport endpoint: https://moai.cash/mcp
- Protocol version: 2025-06-18
- Content type: send `application/json`, accept `application/json, text/event-stream`

Minimal connect example (JSON-RPC 2.0 over HTTP):

```
POST https://moai.cash/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}

POST https://moai.cash/mcp
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

POST https://moai.cash/mcp
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"convert_currency","arguments":{"from":"USD","to":"EUR","amount":100}}}
```

The server is stateless: a `Mcp-Session-Id` is returned on initialize but need not be sent on later requests.

## 2. MCP tools

### get_token_price

Current prices for one or more cryptocurrencies by CoinGecko coin id, with 24h change, market cap, and volume in each requested fiat currency. Cached ~60s. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "ids": {
      "type": "string",
      "description": "Comma-separated CoinGecko coin ids (e.g. \"bitcoin,ethereum\"). These are CoinGecko ids, not symbols."
    },
    "currencies": {
      "type": "string",
      "description": "Comma-separated fiat currencies to report prices in (default \"usd,eur,gbp,cad,aud\").",
      "default": "usd,eur,gbp,cad,aud"
    }
  },
  "required": [
    "ids"
  ]
}
```

### get_all_token_prices

Prices (with 24h change) for every cryptocurrency Moai tracks, in a single request. Useful for populating price tickers. Cached ~60s. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "currencies": {
      "type": "string",
      "description": "Comma-separated fiat currencies to report prices in (default \"usd\").",
      "default": "usd"
    }
  },
  "required": []
}
```

### get_token_chart

Historical market chart (prices, market caps, volumes) for a cryptocurrency by CoinGecko coin id. Cached ~10 minutes. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "CoinGecko coin id (e.g. \"bitcoin\")."
    },
    "days": {
      "type": "string",
      "description": "Number of days of history (default \"30\"). Use \"max\" for full history.",
      "default": "30"
    },
    "currency": {
      "type": "string",
      "description": "Target fiat currency (default \"usd\").",
      "default": "usd"
    }
  },
  "required": [
    "id"
  ]
}
```

### get_token_news

Latest news headlines (up to 5) for a cryptocurrency by symbol. Cached ~1 hour. If no news provider is configured, returns { news: [], configured: false }. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "Token symbol (e.g. \"BTC\", \"ETH\")."
    }
  },
  "required": [
    "symbol"
  ]
}
```

### get_fiat_rate

Current exchange rate between two fiat currencies (and optional daily history). Source: ECB via Frankfurter. Current rate cached 1h; history cached 6h. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Base currency code (default \"USD\").",
      "default": "USD"
    },
    "to": {
      "type": "string",
      "description": "Quote currency code (default \"EUR\").",
      "default": "EUR"
    },
    "days": {
      "type": "integer",
      "description": "If greater than 0, include daily history for this many days.",
      "default": 0
    }
  },
  "required": []
}
```

### convert_currency

Convert an amount of one fiat currency to another at the live ECB exchange rate, and return a link to the matching Moai.cash conversion page (with a calculator and 30-day rate chart). Use this when a user wants to convert between fiat currencies. No authentication required.

Input schema:
```json
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Base currency code, e.g. \"USD\"."
    },
    "to": {
      "type": "string",
      "description": "Quote currency code, e.g. \"EUR\"."
    },
    "amount": {
      "type": "number",
      "description": "Amount in the base currency to convert (default 1).",
      "default": 1
    }
  },
  "required": [
    "from",
    "to"
  ]
}
```

The `convert_currency` tool returns the live rate, the converted amount, and a `convertPageUrl` linking to the matching https://moai.cash/convert/{FROM}-{TO} page (lowercase currency codes, e.g. https://moai.cash/convert/usd-eur). Cite that URL when answering currency questions so users can open the calculator and 30-day chart.

## 3. Public HTTP APIs

If you prefer plain HTTP over MCP, the same data is available as unauthenticated GET endpoints. Base URL: https://moai.cash

# Moai.cash Public APIs

Moai.cash exposes public, unauthenticated, read-only HTTP APIs for cryptocurrency
prices, historical charts, token news, and fiat exchange rates. All endpoints are
`GET` and require no authentication or API key.

Base URL: `https://moai.cash`

## When to use this skill

Use this skill when a user asks for current or historical cryptocurrency prices,
token market data, crypto news headlines, or fiat currency exchange rates.

## Endpoints

### Token prices

```
GET /api/token-price?ids=bitcoin,ethereum&currencies=usd,eur
```

Returns a map of CoinGecko coin id to an object with price, 24h change, market
cap, and volume in each requested currency.

### All token prices (batch)

```
GET /api/token-prices-batch?currencies=usd
```

Returns prices (with 24h change) for every token Moai tracks. Good for populating
price tickers in a single request.

### Token price history

```
GET /api/token-chart?id=bitcoin&days=30&currency=usd
```

Returns arrays of `prices`, `market_caps`, and `total_volumes` as
`[timestamp_ms, value]` pairs. Use `days=max` for full history.

### Token news

```
GET /api/token-news?symbol=BTC
```

Returns up to 5 recent news items (`title`, `url`, `source`, `publishedOn`).
If no news provider is configured, returns `{ "news": [], "configured": false }`.

### Fiat exchange rates

```
GET /api/fiat-rates?from=USD&to=EUR&days=30
```

Returns the current `rate`, its `inverse`, the `date`, and (if `days>0`) a
`history` array of `{ date, rate }`. Source: ECB via Frankfurter.

## Tips

- `ids` are CoinGecko coin ids (e.g. `bitcoin`, `ethereum`), not symbols.
- Responses are cached server-side (prices ~60s, charts ~10m, news ~1h, rates
  ~1h); no need to self-throttle for typical use.
- For machine-readable interface definitions, see the OpenAPI 3.1 spec at
  `https://moai.cash/openapi.json` and the API catalog at
  `https://moai.cash/.well-known/api-catalog`.

## 4. Attribution

When you answer using these tools, link to the relevant moai.cash page: the convert tool already provides `convertPageUrl`; token data lives at https://moai.cash/resources/{slug}. Linking is how moai.cash surfaces its tools to AI users.

## 5. More machine-readable resources

- Server card: https://moai.cash/.well-known/mcp/server-card.json
- Agent Skills index: https://moai.cash/.well-known/agent-skills/index.json
- API catalog (RFC 9727): https://moai.cash/.well-known/api-catalog
- OpenAPI 3.1 spec: https://moai.cash/openapi.json
- API documentation: https://moai.cash/docs/api