# OpenAI Agents

The OpenAI Assistants API supports custom function tools. HelmutPay integrates by exposing its HTTP API as function definitions that the assistant can call.

## Setup

Define the tool functions and their JSON schemas, then wire up a dispatch loop to handle tool calls by making HTTP requests to HelmutPay.

```python
import os
import json
import requests
from openai import OpenAI

HELMUT_API_KEY = os.environ["AGENT_API_KEY"]
BASE_URL = "https://api.helmutpay.com/v1"
HEADERS = {"Authorization": f"Bearer {HELMUT_API_KEY}", "Content-Type": "application/json"}

def helmutpay_send_payment(to: str, amount: str, memo: str = None) -> dict:
    resp = requests.post(
        f"{BASE_URL}/transfers",
        headers=HEADERS,
        json={"to": to, "amount": amount, "currency": "USDC", "memo": memo, "confidential": True},
    )
    return resp.json()

def helmutpay_get_balance() -> dict:
    resp = requests.get(f"{BASE_URL}/account", headers=HEADERS)
    data = resp.json()
    return {"balance": data["balance"], "currency": data["currency"]}

def helmutpay_list_transactions(limit: int = 10) -> dict:
    resp = requests.get(f"{BASE_URL}/transfers?limit={limit}", headers=HEADERS)
    return resp.json()

TOOL_HANDLERS = {
    "helmutpay_send_payment": helmutpay_send_payment,
    "helmutpay_get_balance": helmutpay_get_balance,
    "helmutpay_list_transactions": helmutpay_list_transactions,
}
```

## Tool definitions

Pass these function definitions to the OpenAI assistant:

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "helmutpay_send_payment",
            "description": "Send USDC to a recipient via HelmutPay.",
            "parameters": {
                "type": "object",
                "properties": {
                    "to": {"type": "string", "description": "Handle (@alice) or Solana address"},
                    "amount": {"type": "string", "description": "Decimal amount e.g. '5.00'"},
                    "memo": {"type": "string", "description": "Optional memo"},
                },
                "required": ["to", "amount"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "helmutpay_get_balance",
            "description": "Get the current USDC balance of the agent's HelmutPay wallet.",
            "parameters": {"type": "object", "properties": {}},
        },
    },
    {
        "type": "function",
        "function": {
            "name": "helmutpay_list_transactions",
            "description": "Get recent transaction history.",
            "parameters": {
                "type": "object",
                "properties": {
                    "limit": {"type": "integer", "default": 10},
                },
            },
        },
    },
]
```

## Full example with Assistants API

```python
import json
import os
from openai import OpenAI

openai_client = OpenAI()

# Create assistant with HelmutPay tools
assistant = openai_client.beta.assistants.create(
    name="Payment Agent",
    instructions="You are a helpful agent that can make payments on behalf of the user.",
    tools=tools,
    model="gpt-4o",
)

# Create a thread and run
thread = openai_client.beta.threads.create()
openai_client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Pay @perplexity 0.05 USDC for a search and confirm once done",
)

run = openai_client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# Handle tool calls
while run.status == "requires_action":
    tool_calls = run.required_action.submit_tool_outputs.tool_calls
    tool_outputs = []

    for tool_call in tool_calls:
        fn_name = tool_call.function.name
        fn_args = json.loads(tool_call.function.arguments)
        result = TOOL_HANDLERS[fn_name](**fn_args)
        tool_outputs.append({
            "tool_call_id": tool_call.id,
            "output": json.dumps(result),
        })

    run = openai_client.beta.threads.runs.submit_tool_outputs_and_poll(
        thread_id=thread.id,
        run_id=run.id,
        tool_outputs=tool_outputs,
    )

print(run.status)  # "completed"
```

## Available tools

| Function name                      | Description                                                    |
| ---------------------------------- | -------------------------------------------------------------- |
| `helmutpay_send_payment`           | Send USDC to a handle or address                               |
| `helmutpay_get_balance`            | Get current wallet balance                                     |
| `helmutpay_list_transactions`      | Get recent transaction history                                 |
| `helmutpay_create_payment_request` | Create a payment request link (`POST /v1/transfers/requests`)  |
| `helmutpay_get_transaction`        | Look up a specific transaction by ID (`GET /v1/transfers/:id`) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helmutpay.com/integrations/openai-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.