🤗 HuggingFace SmolAgents
📄 6 Production-Ready Tool Classes

Financial Infrastructure
for SmolAgents

Add wallets, trading, casino play, trustless escrow, domain management, and free USDC bootstrapping to any HuggingFace SmolAgent in under five minutes. Real on-chain capability, clean Python API.

6Services
30+Endpoints
1%Escrow Fee
15%Referral
FreeFaucet USDC

Up and running in 60 seconds

Install SmolAgents, grab a Purple Flea API key from the faucet, and your agent has a funded wallet ready to trade, play, or escrow.

$ pip install smolagents requests
1

Claim your free USDC from the faucet

Visit faucet.purpleflea.com or call the faucet API. New agents receive free USDC to start using all Purple Flea services — casino, trading, escrow — with zero upfront cost.

2

Copy a Tool class into your project

Each Purple Flea service ships as a drop-in SmolAgents Tool class. Paste the class, set PURPLEFLEA_API_KEY, done.

3

Add tools to your ToolCallingAgent

Pass any combination of Purple Flea tools to ToolCallingAgent(tools=[...]). The agent decides autonomously when to trade, gamble, or send payments.

4

Deploy and earn referral income

Every agent you deploy with a referral code earns 15% of escrow fees from users it brings in. Build a fleet, earn passive income from the protocol.

Six services, one unified API

Every Purple Flea service is accessible via REST. Each maps to a single SmolAgents Tool class your agent can call autonomously.

🎲

Casino API

Provably fair dice, slots, roulette, and card games. Agents bet, track win rates, and optimize strategies autonomously. Real USDC payouts, on-chain settlement.

purpleflea.com/casino-api
📈

Trading API

Spot and perpetual markets, limit/market orders, price oracles, and portfolio tracking. Supports major crypto pairs with low-latency execution.

purpleflea.com/trading-api
💳

Wallet API

Non-custodial wallets for agents. Generate addresses, check balances, send USDC across EVM chains. BIP-39 derivation, multi-chain support.

purpleflea.com/wallet-api
🌐

Domains API

Register, transfer, and monetize .agent and blockchain domains. Agents can autonomously acquire domains as tradeable assets or identity infrastructure.

purpleflea.com/domains-api
💰

Faucet

Free USDC for new agents. Register once, claim funds, and immediately start using all six Purple Flea services. No credit card, no KYC, instant delivery.

faucet.purpleflea.com
🔒

Escrow

Trustless agent-to-agent payments with 1% fee and 15% referral earnings. Lock funds until conditions are met. Perfect for multi-agent task pipelines.

escrow.purpleflea.com

Six drop-in Tool classes for SmolAgents

Each class implements the SmolAgents Tool interface. Copy, configure, and add to your agent.

Casino Tool — Provably fair casino bets

Python
import requests
from smolagents import Tool

class CasinoTool(Tool):
    name = "casino"
    description = (
        "Place a bet at the Purple Flea casino. "
        "Supports: dice, slots, roulette, blackjack. "
        "Returns win/loss result and updated balance."
    )
    inputs = {
        "game":   {"type": "string", "description": "Game type: dice | slots | roulette | blackjack"},
        "amount": {"type": "number", "description": "Bet amount in USDC"},
        "params": {"type": "string", "description": "Optional JSON with game-specific params", "nullable": "true"},
    }
    output_type = "string"

    def __init__(self, api_key: str):
        super().__init__()
        self.api_key = api_key
        self.base = "https://purpleflea.com/casino-api"

    def forward(self, game: str, amount: float, params: str = "{}") -> str:
        import json
        resp = requests.post(
            f"{self.base}/bet",
            headers={"Authorization": f"Bearer {self.api_key}"},
            json={"game": game, "amount": amount, "params": json.loads(params)},
        )
        resp.raise_for_status()
        data = resp.json()
        result = "WIN" if data["win"] else "LOSS"
        return (
            f"{result}: bet {amount} USDC on {game}. "
            f"Payout: {data['payout']} USDC. Balance: {data['balance']} USDC. "
            f"Provably fair seed: {data['seed']}"
        )

Trading Tool — Spot & perpetual order placement

Python
class TradingTool(Tool):
    name = "trading"
    description = (
        "Place buy/sell orders on Purple Flea trading. "
        "Supports spot and perpetual markets. Returns order ID, fill price, status."
    )
    inputs = {
        "pair":       {"type": "string", "description": "Trading pair, e.g. BTC-USDC"},
        "side":       {"type": "string", "description": "buy or sell"},
        "amount":     {"type": "number", "description": "Order size in USDC"},
        "order_type": {"type": "string", "description": "market | limit"},
        "price":      {"type": "number", "description": "Limit price (required if limit)", "nullable": "true"},
    }
    output_type = "string"

    def __init__(self, api_key: str):
        super().__init__()
        self.api_key = api_key

    def forward(self, pair: str, side: str, amount: float,
                order_type: str = "market", price: float = None) -> str:
        payload = {"pair": pair, "side": side, "amount": amount, "type": order_type}
        if price:
            payload["price"] = price
        resp = requests.post(
            "https://purpleflea.com/trading-api/order",
            headers={"Authorization": f"Bearer {self.api_key}"},
            json=payload,
        )
        resp.raise_for_status()
        d = resp.json()
        return (
            f"Order {d['order_id']}: {side.upper()} {amount} USDC of {pair} "
            f"at {d['fill_price']}. Status: {d['status']}"
        )

Escrow Tool — Trustless agent-to-agent payments

Python
class EscrowTool(Tool):
    name = "escrow"
    description = (
        "Lock USDC in trustless escrow for agent-to-agent payments. "
        "Actions: create, release, refund, status. 1% fee. Returns escrow ID."
    )
    inputs = {
        "action":    {"type": "string", "description": "create | release | refund | status"},
        "amount":    {"type": "number", "description": "USDC amount (for create)", "nullable": "true"},
        "receiver":  {"type": "string", "description": "Receiver agent ID (for create)", "nullable": "true"},
        "escrow_id": {"type": "string", "description": "Escrow ID (for release/refund/status)", "nullable": "true"},
    }
    output_type = "string"

    def __init__(self, api_key: str):
        super().__init__()
        self.api_key = api_key
        self.base = "https://escrow.purpleflea.com"
        self.headers = {"Authorization": f"Bearer {api_key}"}

    def forward(self, action: str, amount: float = None,
                receiver: str = None, escrow_id: str = None) -> str:
        if action == "create":
            resp = requests.post(f"{self.base}/escrow", headers=self.headers,
                                   json={"amount": amount, "receiver": receiver})
            resp.raise_for_status()
            d = resp.json()
            return f"Escrow created: ID={d['escrow_id']}, amount={amount} USDC, fee={d['fee']} USDC"
        elif action in ("release", "refund"):
            resp = requests.post(
                f"{self.base}/escrow/{escrow_id}/{action}", headers=self.headers)
            resp.raise_for_status()
            return f"Escrow {escrow_id} {action}d successfully: {resp.json()['status']}"
        elif action == "status":
            resp = requests.get(f"{self.base}/escrow/{escrow_id}", headers=self.headers)
            d = resp.json()
            return f"Escrow {escrow_id}: status={d['status']}, amount={d['amount']} USDC"
        return "Unknown action"

Complete autonomous agent example

A full SmolAgent that claims faucet funds, places trades, bets at the casino, and pays collaborators via escrow — all from natural language instructions.

Claim Faucet
Check Balance
Trade BTC
Casino Bet
Escrow Pay
Report P&L
Python — complete_agent.py
"""
Complete SmolAgents + Purple Flea example.
The agent autonomously manages a crypto portfolio,
plays casino games, and pays collaborators via escrow.
"""
import os, requests
from smolagents import ToolCallingAgent, HfApiModel, Tool

PURPLEFLEA_KEY = os.getenv("PURPLEFLEA_API_KEY")  # from faucet.purpleflea.com
HF_TOKEN       = os.getenv("HF_TOKEN")

class FaucetTool(Tool):
    name = "faucet"
    description = "Register a new agent and claim free USDC from the Purple Flea faucet."
    inputs = {"agent_id": {"type": "string", "description": "Unique ID for this agent"}}
    output_type = "string"
    def forward(self, agent_id: str) -> str:
        resp = requests.post("https://faucet.purpleflea.com/register",
            json={"agent_id": agent_id, "referrer": "smolagents"})
        resp.raise_for_status()
        d = resp.json()
        return f"Registered {agent_id}. Claimed {d['amount']} USDC. Key: {d['api_key']}"

class WalletTool(Tool):
    name = "wallet"
    description = "Manage wallet. Actions: balance | send | address. Chain: ethereum | base | arbitrum."
    inputs = {
        "action": {"type": "string", "description": "balance | send | address"},
        "to":     {"type": "string", "description": "Recipient address", "nullable": "true"},
        "amount": {"type": "number", "description": "USDC amount", "nullable": "true"},
    }
    output_type = "string"
    def __init__(self, api_key): super().__init__(); self.h = {"Authorization": f"Bearer {api_key}"}
    def forward(self, action, to=None, amount=None):
        base = "https://purpleflea.com/wallet-api"
        if action == "balance":
            d = requests.get(f"{base}/balance", headers=self.h).json()
            return f"Balance: {d['usdc']} USDC / {d['eth']} ETH"
        elif action == "send":
            d = requests.post(f"{base}/send", headers=self.h,
                               json={"to": to, "amount": amount}).json()
            return f"Sent {amount} USDC to {to}. TX: {d['tx_hash']}"
        elif action == "address":
            return requests.get(f"{base}/address", headers=self.h).json()["address"]

# Build the multi-tool agent
model = HfApiModel(model_id="meta-llama/Meta-Llama-3.1-70B-Instruct", token=HF_TOKEN)

agent = ToolCallingAgent(
    tools=[
        FaucetTool(),
        WalletTool(PURPLEFLEA_KEY),
        TradingTool(PURPLEFLEA_KEY),
        CasinoTool(PURPLEFLEA_KEY),
        EscrowTool(PURPLEFLEA_KEY),
    ],
    model=model,
    max_steps=12,
)

result = agent.run("""
1. Check my current USDC balance.
2. Place a market buy of 50 USDC of BTC-USDC.
3. Bet 5 USDC on dice at the casino.
4. Create an escrow of 20 USDC to agent 'collaborator-7'.
5. Report final balance and summarize all actions.
""")
print(result)
Pro tip: Set verbosity_level=2 to see each tool call and its raw response. Use max_steps=20 for longer autonomous sessions. Swap HfApiModel for LiteLLMModel to run a local model.

What each Tool class can do

Full capability matrix across all six Purple Flea services.

ToolKey ActionsAuthFeeReal-time
CasinoToolBet, history, verify provability, claim winningsBearerHouse edgeYes
TradingToolMarket/limit orders, cancel, portfolio, price feedBearer0.1% takerYes
WalletToolBalance, send, receive, multi-chain addressesBearerGas onlyYes
DomainsToolRegister, lookup, renew, transfer, listBearerPer domain
FaucetToolRegister agent, claim USDC, check eligibilityNoneFreeYes
EscrowToolCreate, release, refund, dispute, statusBearer1% + 15% refYes

Built for the HuggingFace ecosystem

SmolAgents is HuggingFace's lightweight agent framework — clean Python, minimal dependencies, and first-class support for open models via the Inference API. Purple Flea's Tool classes integrate natively.

Run any open model — Llama 3, Mistral, Qwen, Gemma — as the planning backbone for your on-chain agent. No vendor lock-in, full model freedom.

  • Works with any HuggingFace Inference API model
  • Works with local models via LiteLLM or Ollama
  • Minimal Python dependencies (just requests + smolagents)
  • Tool classes are self-contained, no extra packages needed
  • Compatible with both CodeAgent and ToolCallingAgent
  • Easy to extend with custom business logic
Python — local Ollama model
# Use a local Ollama model instead of HF API
from smolagents import ToolCallingAgent, LiteLLMModel

model = LiteLLMModel(
    model_id="ollama/llama3.2",
    api_base="http://localhost:11434",
)

agent = ToolCallingAgent(
    tools=[
        CasinoTool(PURPLEFLEA_KEY),
        TradingTool(PURPLEFLEA_KEY),
        EscrowTool(PURPLEFLEA_KEY),
    ],
    model=model,
    max_steps=8,
)

result = agent.run(
    "Trade 100 USDC into ETH, then bet 10% of "
    "any winnings at the casino dice table."
)
print(result)
💰

New agent? Start with free USDC

The Purple Flea faucet gives every new agent free USDC to try all six services with zero risk. Register in one API call — no credit card, no KYC.

Ready to give your SmolAgent
real financial power?

Six tool classes, one API key, zero infrastructure to run. Get started with the free faucet in under a minute.