DocsCookbooks

Cookbooks

Copy-paste recipes for common use cases. Each cookbook is a self-contained example you can adapt to your own agent architecture.

Recipe A

LangChain Research Agent

Build a LangChain agent that can autonomously access premium paywalled APIs. The agent decides when to use the tool, and smart_fetch handles the payment negotiation transparently.

1. Define the Modexia tool

Create a custom LangChain @tool that wraps smart_fetch. The LLM will invoke this tool whenever it needs premium data.

python
from langchain.tools import tool
from modexia import ModexiaClient

client = ModexiaClient(api_key="mx_test_...")

@tool
def fetch_premium_news(query: str) -> str:
    """Fetch premium financial news articles. Automatically pays
    if the API requires payment via the x402 protocol."""
    url = f"https://api.premium-news.com/v1/search?q={query}"
    response = client.smart_fetch(url)
    if response.ok:
        return response.json()["summary"]
    return f"Error: {response.status_code}"

2. Wire it into a LangChain agent

Pass the tool to any LangChain agent. The LLM decides when to invoke it based on the user query.

python
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o")

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a financial research assistant. "
               "Use the fetch_premium_news tool to find relevant data."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_openai_tools_agent(llm, [fetch_premium_news], prompt)
executor = AgentExecutor(agent=agent, tools=[fetch_premium_news])

# The LLM will call fetch_premium_news, which auto-pays via x402
result = executor.invoke({"input": "What is the latest on NVIDIA earnings?"})
print(result["output"])

How billing works here

Each time the LLM invokes fetch_premium_news, the SDK checks if the API returns HTTP 402. If it does, your agent pays the micro-fee (e.g. $0.01) from its wallet automatically. You only pay for what you use.

Recipe B

Agent-to-Agent Economy (A2A)

Build autonomous economic relationships between agents. In this example, a Manager Agent pays a Worker Agent (Freelancer) for completing a task — no human approval needed.

Scenario

The Manager Agent outsources a data-labeling task. Once the Worker confirms completion, the Manager pays the Worker's wallet address directly.

python
from modexia import ModexiaClient

# Manager Agent's client (funds come from Manager's wallet)
manager = ModexiaClient(api_key="mx_test_manager_key...")

# Worker Agent's wallet address (retrieved from their profile)
WORKER_WALLET = "0x742d35Cc6634C0532925a3b844Bc454e..."

def pay_worker_for_task(task_id: str, amount: float):
    """Pay the Worker Agent upon verified task completion."""
    receipt = manager.transfer(
        recipient=WORKER_WALLET,
        amount=amount,
        idempotency_key=f"task-payment-{task_id}",  # prevents double-pay
        wait=True
    )

    if receipt["success"]:
        print(f"Paid {amount} credits for task {task_id}")
        print(f"Transaction: {receipt['txHash']}")
    else:
        print(f"Payment failed: {receipt}")

# Manager verifies the work is done, then pays
pay_worker_for_task(task_id="label-batch-042", amount=2.50)

Scaling A2A economies

Each agent can have its own API key and wallet. Use Spending Policies to cap what each agent can spend per day. The idempotency_key ensures that even if the Manager retries the payment (e.g. due to a network glitch), the Worker only gets paid once.