> ## 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.

# Bring Your Own Frontend

> Integrate CoinFello directly into your own app

Build CoinFello into your own frontend by hitting the A2A endpoint directly. The API follows the [Agent-to-Agent protocol spec](https://a2a-protocol.org/latest/).

<Card title="Demo Project" icon="github" href="https://github.com/CoinFello/byof-demo">
  A working example app showing authentication, streaming, and client-side tool call handling.
</Card>

## Endpoint

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

All requests use [JSON-RPC 2.0](https://www.jsonrpc.org/specification).

## 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 length) |
| `tasks/cancel`   | Cancel a running task                              |

## Agent ID

Every `message/send` and `message/stream` request must include an `agentId`. The endpoint is agent-agnostic — the agent is resolved at request time from the value you supply.

Pass it in `params.configuration`:

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

Omitting `agentId` on a new request returns: `"agentId is required: provide in configuration.agentId or as a DataPart"`. Once a task exists, subsequent messages that include its `taskId` do not need to repeat it.

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

## Example: 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?" }]
      }
    }
  }'
```

## Streaming

Use `message/stream` to get Server-Sent Events back. Each event 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" }]
      }
    }
  }'
```

## Authentication

Authentication uses SIWE (Sign-In with Ethereum). Complete the SIWE flow to obtain a session cookie before making requests. See [Authentication](/api-reference/authentication) for the full flow with curl examples.

## Client-side tool calls

The CoinFello chat agent which you can get from [its agent card](https://app.coinfello.com/agent/chat/.well-known/agent-card.json) returns tool call requests as part of its A2A responses. Your frontend is responsible for handling these calls — rendering UI, prompting the user for approval, executing wallet transactions, and returning results back to the agent.

Tool calls appear in the agent's response as `functionCall` parts:

```json theme={null}
{
  "role": "agent",
  "parts": [
    {
      "type": "functionCall",
      "name": "execute_lifi_swap",
      "id": "call_abc123",
      "parameters": {
        "fromChainId": 1,
        "toChainId": 1,
        "fromTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "toTokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "fromAmount": "100000000000000000",
        "slippage": 0.005,
        "fromTokenSymbol": "ETH",
        "toTokenSymbol": "USDC",
        "fromTokenDecimals": 18,
        "toTokenDecimals": 6
      }
    }
  ]
}
```

After the user approves or the action completes, submit the result back via `message/send` with a `functionReturn` part:

```json theme={null}
{
  "role": "user",
  "parts": [
    {
      "type": "functionReturn",
      "id": "call_abc123",
      "name": "execute_lifi_swap",
      "result": { "txHash": "0xabc..." }
    }
  ]
}
```

### Tool reference

<AccordionGroup>
  <Accordion title="call_smart_contract_function">
    Proposes a generic smart contract call for the user to approve or reject. Display the contract address, function name, arguments, and value before submitting the transaction.

    | Parameter      | Type       | Description                             |
    | -------------- | ---------- | --------------------------------------- |
    | `to`           | `string`   | Contract address                        |
    | `functionName` | `string`   | Name of the contract function           |
    | `args`         | `string[]` | Encoded function arguments              |
    | `chainId`      | `number`   | Target chain ID                         |
    | `value`        | `string`   | Native token value in wei               |
    | `abi`          | `string[]` | ABI fragments needed to encode the call |
  </Accordion>

  <Accordion title="send_native_gas_token">
    Sends native gas token (e.g. ETH) to an address. Show the recipient and amount for user confirmation before broadcasting.

    | Parameter | Type     | Description       |
    | --------- | -------- | ----------------- |
    | `to`      | `string` | Recipient address |
    | `chainId` | `number` | Target chain ID   |
    | `value`   | `string` | Amount in wei     |
  </Accordion>

  <Accordion title="transfer_nft">
    Transfers an NFT to another address. Display the NFT details and recipient before the user approves.

    | Parameter         | Type     | Description                                  |
    | ----------------- | -------- | -------------------------------------------- |
    | `contractAddress` | `string` | NFT contract address                         |
    | `tokenId`         | `string` | Token ID                                     |
    | `toAddress`       | `string` | Recipient address                            |
    | `amount`          | `string` | Amount (for ERC-1155; use `"1"` for ERC-721) |
    | `chainId`         | `number` | Target chain ID                              |
  </Accordion>

  <Accordion title="show_token_balance_ui">
    Requests a visual token balance display. Render balance cards or a portfolio summary using the provided data — no wallet transaction required.

    | Parameter    | Type       | Description                                                               |
    | ------------ | ---------- | ------------------------------------------------------------------------- |
    | `address`    | `string`   | Wallet address                                                            |
    | `balances`   | `object[]` | Array of token balance objects (symbol, amount, price, value, logo, etc.) |
    | `totalValue` | `number`   | Total portfolio value in USD                                              |
  </Accordion>

  <Accordion title="execute_lifi_swap">
    Executes a token swap or cross-chain bridge via LI.FI. Fetch a quote from LI.FI using the provided parameters, show the route to the user, then execute on approval.

    | Parameter           | Type     | Description                                |
    | ------------------- | -------- | ------------------------------------------ |
    | `fromChainId`       | `number` | Source chain ID                            |
    | `toChainId`         | `number` | Destination chain ID                       |
    | `fromTokenAddress`  | `string` | Source token address                       |
    | `toTokenAddress`    | `string` | Destination token address                  |
    | `fromAmount`        | `string` | Amount in source token's smallest unit     |
    | `slippage`          | `number` | Slippage tolerance (e.g. `0.005` for 0.5%) |
    | `fromTokenSymbol`   | `string` | Source token symbol                        |
    | `toTokenSymbol`     | `string` | Destination token symbol                   |
    | `fromTokenDecimals` | `number` | Source token decimals                      |
    | `toTokenDecimals`   | `number` | Destination token decimals                 |
  </Accordion>

  <Accordion title="enter_staking_yield">
    Prepares a staking transaction for a specific yield opportunity. Show the APY, protocol, pool, and lockup period before requesting approval.

    | Parameter            | Type       | Description                    |
    | -------------------- | ---------- | ------------------------------ |
    | `yieldId`            | `string`   | Yield opportunity ID           |
    | `amount`             | `string`   | Amount to stake                |
    | `walletAddress`      | `string`   | User's wallet address          |
    | `tokenSymbol`        | `string`   | Token to stake                 |
    | `tokenAddress`       | `string`   | Token contract address         |
    | `chainId`            | `number`   | Target chain ID                |
    | `network`            | `string`   | Network name                   |
    | `protocol`           | `string`   | Protocol name                  |
    | `poolName`           | `string`   | Pool name                      |
    | `apy`                | `number`   | Current APY                    |
    | `lockupPeriod`       | `string`   | Human-readable lockup duration |
    | `rewardTokenSymbols` | `string[]` | Reward token symbols           |
  </Accordion>

  <Accordion title="exit_staking_yield">
    Prepares an unstaking transaction to withdraw from a staking position.

    | Parameter       | Type     | Description           |
    | --------------- | -------- | --------------------- |
    | `yieldId`       | `string` | Yield opportunity ID  |
    | `amount`        | `string` | Amount to withdraw    |
    | `walletAddress` | `string` | User's wallet address |
  </Accordion>

  <Accordion title="aave_supply / aave_borrow / aave_repay / aave_withdraw">
    Aave V4 lending market interactions. All four share the same parameter shape and require user approval before executing.

    | Parameter       | Type     | Description                     |
    | --------------- | -------- | ------------------------------- |
    | `marketAddress` | `string` | Aave market contract address    |
    | `tokenAddress`  | `string` | Token contract address          |
    | `tokenSymbol`   | `string` | Token symbol                    |
    | `amount`        | `string` | Amount in token's smallest unit |
    | `walletAddress` | `string` | User's wallet address           |
    | `chainId`       | `number` | Target chain ID                 |
  </Accordion>

  <Accordion title="request_auto_rebalance_permission">
    Asks the user to grant permission for automatic yield rebalancing. Display the current position, minimum yield increase threshold, and maximum lockup before the user accepts or declines.

    | Parameter                  | Type     | Description                                  |
    | -------------------------- | -------- | -------------------------------------------- |
    | `chainId`                  | `number` | Target chain ID                              |
    | `tokenAddress`             | `string` | Token to rebalance                           |
    | `currentPosition.protocol` | `string` | Current protocol                             |
    | `currentPosition.amount`   | `string` | Current staked amount                        |
    | `currentPosition.apy`      | `number` | Current APY                                  |
    | `minYieldIncrease`         | `number` | Minimum APY improvement to trigger rebalance |
    | `maxLockupDays`            | `number` | Maximum lockup days the user will accept     |
  </Accordion>
</AccordionGroup>

## React Package

Interested in a drop-in `@coinfello/react` package? [Reach out to us](https://coinfello.com) — it's on the roadmap.