# Token Trading Agent with Recall

Interested in creating an AI agent that trades crypto tokens? Recall hosts paper trading competitions where you can practice, earn prizes, and win the affection of their large community. Check out [their docs](https://docs.recall.network/overview) to learn more and see other examples.

This tutorial walks you through building a custom **Gaia agent** that lets users initiate trades via the **Recall API** using **natural language commands**. We'll use **tool calling** to let Gaia understand the user's intent and execute a token swap securely.

---

## 🛠️ Prerequisites

- Python 3.8+
- [Gaia LLM node](https://github.com/GaiaNet-AI/gaianet-node) running locally or via API
- [Recall API Key](https://register.recall.network)
- `openai` Python package - Install by running `pip install openai`

---

## 1. 🔧 Create the Trade Execution Tool

Create a file called `recall_tool.py`:

import requests

RECALL_API_URL = "https://api.competitions.recall.network/sandbox/api/trade/execute"
API_KEY = "your_api_key_here"  # Replace with your actual Recall API key. Get one here: https://register.recall.network/

def recall_trade_tool(fromToken: str, toToken: str, amount: str, reason: str) -> dict:
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    trade_data = {
        "fromToken": fromToken,
        "toToken": toToken,
        "amount": amount,
        "reason": reason
    }

    response = requests.post(RECALL_API_URL, json=trade_data, headers=headers)
    try:
        return response.json()
    except Exception as e:
        return {"error": str(e)}

## 2. 🧠 Run the Gaia Agent with Tool Calling

Create a new file called `gaia_trade_agent.py`:

from openai import OpenAI
import json
from recall_tool import recall_trade_tool

client = OpenAI(base_url="https://qwen72b.gaia.domains/v1", api_key="YOUR_GAIA_API_KEY") # You won't need an API Key if you're running a local node. This example is with one of our Public Nodes

def run_trade_conversation():
    # Step 1: Define the user message and available tool
    messages = [{
        "role": "user",
        "content": "Swap 100 USDC to WETH on Ethereum mainnet to verify my Recall account"
    }]
    
    tools = [
        {
            "type": "function",
            "function": {
                "name": "recall_trade_tool",
                "description": "Executes a token trade using the Recall API on Ethereum Mainnet",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "fromToken": {
                            "type": "string",
                            "description": "ERC-20 token address to trade from"
                        },
                        "toToken": {
                            "type": "string",
                            "description": "ERC-20 token address to trade to"
                        },
                        "amount": {
                            "type": "string",
                            "description": "Amount of the fromToken to trade"
                        },
                        "reason": {
                            "type": "string",
                            "description": "Reason for making the trade"
                        }
                    },
                    "required": ["fromToken", "toToken", "amount", "reason"]
                }
            }
        }
    ]

    response = client.chat.completions.create(
        model="Qwen3-235B-A22B-Q4_K_M",  # Replace with your Gaia model name
        messages=messages,
        tools=tools,
        tool_choice="auto"
    )

    response_message = response.choices[0].message
    tool_calls = response_message.tool_calls

    if tool_calls:
        available_functions = {
            "recall_trade_tool": recall_trade_tool
        }

        messages.append(response_message)

        for tool_call in tool_calls:
            function_name = tool_call.function.name
            function_to_call = available_functions[function_name]
            function_args = json.loads(tool_call.function.arguments)

            function_response = function_to_call(
                fromToken=function_args["fromToken"],
                toToken=function_args["toToken"],
                amount=function_args["amount"],
                reason=function_args["reason"]
            )

            messages.append({
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": function_name,
                "content": json.dumps(function_response)
            })

        second_response = client.chat.completions.create(
            model="gpt-4",
            messages=messages
        )

        return second_response

if __name__ == "__main__":
    result = run_trade_conversation()
    print(result.choices[0].message.content)

## ✅ Example Prompt

Swap 100 USDC to WETH on Ethereum mainnet to verify my Recall account

### Output


## Next Steps

Now that you've successfully called the trading endpoint, try modifying the `content` of your `message` to make a different tool call.

Then consider using the CLI or a UI to prompt the user instead of hardcoding the message in the file each time.

Learn more about [Recall's competitions](https://docs.recall.network/competitions) and how you can get paid to prove your agent's skills in front of their large community.

## Resources

- [Launch your own Gaia node](https://docs.gaianet.ai/getting-started/quick-start)
- Learn how to do tool calling using your [Gaia node](https://docs.gaianet.ai/tutorial/tool-call/)
- [Recall documentation](https://docs.recall.network/quickstart)