> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinfello.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Integrate CoinFello into your applications

## A2A Endpoint

CoinFello exposes a single API endpoint that implements the [Agent-to-Agent protocol spec](https://a2a-protocol.org/latest/) over JSON-RPC 2.0.

```
POST https://app.coinfello.com/api/a2a
```

### Methods

| Method           | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `message/send`   | Send a message and get a response                                |
| `message/stream` | Send a message and stream the response via SSE                   |
| `tasks/get`      | Get a task by ID (optionally limit history with `historyLength`) |
| `tasks/cancel`   | Cancel a running task                                            |

### Agent ID

Every `message/send` and `message/stream` request must include an `agentId` so the endpoint knows which agent to route the message to. The endpoint is agent-agnostic — there is no hardcoded default.

Pass the `agentId` (a number) in `params.configuration`:

```json theme={null}
{
  "params": {
    "configuration": { "agentId": 1 },
    "message": { ... }
  }
}
```

Omitting the `agentId` on a new request returns an error: `"agentId is required: provide in configuration.agentId or as a DataPart"`. Subsequent messages that reference an existing `taskId` do not need to repeat it.

Retrieve the agent's numeric ID from the [agent card](https://app.coinfello.com/agent/chat/.well-known/agent-card.json) under skills where each entry is a separate chat agent.

### Send a Message

```bash theme={null}
curl -b cookies.txt -X POST https://app.coinfello.com/api/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "configuration": { "agentId": 1 },
      "message": {
        "role": "user",
        "parts": [{ "type": "text", "text": "What are the best yields for ETH right now?" }]
      }
    }
  }'
```

### Stream a Response

Use `message/stream` to receive Server-Sent Events. Each SSE `data` line is a JSON-RPC response wrapping an A2A stream event.

```bash theme={null}
curl -b cookies.txt -X POST https://app.coinfello.com/api/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/stream",
    "params": {
      "configuration": { "agentId": 1 },
      "message": {
        "role": "user",
        "parts": [{ "type": "text", "text": "Swap 0.1 ETH to USDC" }]
      }
    }
  }'
```

### Get a Task

```bash theme={null}
curl -X POST https://app.coinfello.com/api/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tasks/get",
    "params": { "id": "task-id-here", "historyLength": 5 }
  }'
```

### Cancel a Task

```bash theme={null}
curl -X POST https://app.coinfello.com/api/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tasks/cancel",
    "params": { "id": "task-id-here" }
  }'
```

## Authentication

Authentication uses SIWE (Sign-In with Ethereum). Complete the SIWE flow to obtain a session cookie before making requests. Unauthenticated requests return a `401` error.

See the [Authentication](/api-reference/authentication) page for the full SIWE flow with curl examples.

## Errors

Errors follow standard JSON-RPC 2.0 error format:

| Code     | Meaning                  |
| -------- | ------------------------ |
| `-32600` | Invalid JSON-RPC request |
| `-32601` | Unknown method           |
| `-32001` | Task not found           |
| `-32002` | Task not cancelable      |
| `-32603` | Internal server error    |

## Rate Limits

API requests are rate-limited. Current limits are provided in response headers:

| Header                  | Description                           |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute           |
| `X-RateLimit-Remaining` | Requests remaining in current window  |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets |