---
name: machima
version: 2.1.0
description: The search engine for AI agents. Describe what you need, Machima finds and executes the best plugin.
homepage: https://prism.machima.ai
metadata: {"moltbot":{"emoji":"🔥","category":"protocol","api_base":"https://api.prism.machima.ai/api/v1"}}
---

# Machima

The search engine for AI agents. Describe what you need in natural language — Machima finds the best plugin across the network to fulfill it, and executes it on your behalf.

**Base URL:** `https://api.prism.machima.ai/api/v1`

---

## Quick Start

```bash
# 1. Register your agent
curl -X POST https://api.prism.machima.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_agent",
    "client_type": "generic",
    "wallet_address": "0xYourWalletAddress"
  }'
# Save the api_key from the response!

# 2. Search — describe what you need
curl -X POST https://api.prism.machima.ai/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Check wallet balances for jesse.base.eth on Base"}'

# 3. Select a plugin from results (reply with the number)
curl -X POST https://api.prism.machima.ai/api/v1/search/SESSION_ID/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "1"}'

# 4. Confirm execution
curl -X POST https://api.prism.machima.ai/api/v1/search/SESSION_ID/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "yes"}'
```

---

## Register

```bash
curl -X POST https://api.prism.machima.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "your_agent_name",
    "client_type": "generic",
    "wallet_address": "0xYourEvmWalletAddress",
    "description": "What your agent does"
  }'
```

**Required:** `name` (lowercase alphanumeric + underscores, 2-64 chars), `client_type` (`generic`), `wallet_address` (EVM address)

**Save your `api_key` immediately.** You won't see it again.

---

## Authentication

All requests use Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

---

## Search

The primary way to use Machima. Start a search, describe what you need, and Machima's concierge guides you through discovery, selection, and execution.

### Start a search

```bash
curl -X POST https://api.prism.machima.ai/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What tokens does jesse.base.eth hold on Base?"}'
```

### Continue the session

Send follow-up messages to select, confirm, or clarify:

```bash
curl -X POST https://api.prism.machima.ai/api/v1/search/SESSION_ID/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "1"}'
```

### Session flow

1. **searching** — Machima is finding matching plugins via ClawRank
2. **awaiting_selection** — Multiple matches found, pick one by number
3. **confirming_execution** — Confirm with "yes" to execute, "no" to cancel
4. **executing** — Plugin is running
5. **completed** — Done, results returned

### Message options

**Select a plugin:** `{"message": "1"}` or `{"message": "1", "selection": 1}`

**Confirm execution:** `{"message": "yes"}` or `{"message": "yes", "confirm": true}`

**Cancel:** `{"message": "cancel", "cancel": true}`

### Get session state

```bash
curl https://api.prism.machima.ai/api/v1/search/SESSION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### List sessions

```bash
curl https://api.prism.machima.ai/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Browse Plugins

See what's available on the network. No auth required.

```bash
curl https://api.prism.machima.ai/api/v1/plugins
```

```bash
curl https://api.prism.machima.ai/api/v1/plugins/PLUGIN_ID
```

---

## ClawRank

ClawRank is Machima's matching algorithm. It ranks plugins against your query using embedding similarity + LLM validation.

| Score | Meaning |
|-------|---------|
| 80+ | Excellent match |
| 60-79 | Good match |
| 40-59 | Partial match |
| <40 | Weak but LLM-validated |

---

## Response Format

```json
{"ok": true, "data": {...}}
{"ok": false, "error": "Description", "code": "ERROR_CODE"}
```

---

## Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
| `NOT_FOUND` | 404 | Resource not found |
| `INVALID_INPUT` | 400 | Request body validation failed |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Server error |

---

**Website:** https://prism.machima.ai