> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents & Tools with Atoa Agent Pay

> Turn the Atoa Agent Pay SDK into a tool surface any model can use. Wire up the tools, run the loop and keep every capability enforced server-side.

`createAgentPayTools(atoa)` returns tool definitions you can hand to any model, plus a `call()` dispatcher that
runs whatever the model picks.

The tools can only do what your API key permits. Spending limits live on the contract and are enforced by Atoa's
servers, so the model can't exceed them.

## Wire-up

```python Python theme={null}
from atoa_agent_pay import init, create_agent_pay_tools

atoa = init(environment="sandbox")                               # reads ATOA_API_KEY
atoa.agent.register(name="Checkout copilot")

tools = create_agent_pay_tools(atoa)
tools.specs                                # tool definitions — hand these to your model
```

```typescript TypeScript theme={null}
import { createAgentPayClient, createAgentPayTools } from "@atoapayments/agent-pay";

const atoa = createAgentPayClient({ environment: "sandbox" });   // reads ATOA_API_KEY
await atoa.agent.register({ name: "Checkout copilot" });

const tools = createAgentPayTools(atoa);
tools.tools;                               // tool definitions — hand these to your model
```

The definitions carry the usage guidance a model needs — required fields, defaults, when to ask the user — so you
don't write tool prompts yourself.

## The loop

The loop works with any model provider: hand the model the definitions, run what it calls, feed the result back.

```python Python theme={null}
# 1 — give the model tools.specs as its available tools
# 2 — when it returns a tool call, execute it:
out = tools.call(tool_call.name, tool_call.arguments)
# out: { "result", "text", "isError" } — text is model-ready; errors come back in-band, not raised
# 3 — return out["text"] to the model and continue until it's done
```

```typescript TypeScript theme={null}
// 1 — give the model tools.tools as its available tools
// 2 — when it returns a tool call, execute it:
const out = await tools.call(toolCall.name, toolCall.arguments);
// out: { result, text, isError } — text is model-ready; errors come back in-band, not thrown
// 3 — return out.text to the model and continue until it's done
```

## The tools

**23 tools.** Each maps to the SDK method of the same name — parameters and behaviour are identical, so the
[reference](https://docs.paywithatoa.com/agent-pay/reference.md#methods) covers both.

### Setup & sandbox

| Tool | Purpose |
| - | - |
| `check_availability` | Health probe — never errors. |
| `get_agent` | Which persona this session operates as — call it **before** `register_agent`; if it reports `registered: true`, reuse that persona instead of registering again. |
| `register_agent` | Register the agent (idempotent on the same key). Only call it when `get_agent` reports no agent yet. |
| `get_sandbox_test_accounts` | The sandbox SEND accounts and the outcome each forces. |

### Contracts

| Tool | Purpose |
| - | - |
| `create_contract` | Create a `SEND` or `COLLECT` contract — returns the `authorizationUrl` a human approves. COLLECT can bundle a [first charge](https://docs.paywithatoa.com/agent-pay/collect.md#charge-on-approval) into that approval (`initialChargeAmount` + `initialChargeOrderId`). |
| `get_contract` | Read a contract, including live `usage` headroom. |
| `list_contracts` | Filter by `type`, `status`, or customer. |
| `update_contract` | Change `limits` — returns a new `authorizationUrl` to re-approve. |
| `revoke_contract` | Revoke (terminal). |

### Payments

| Tool | Purpose |
| - | - |
| `collect_payment` | Money in — a pay-link, or an off-session charge with a `contractId`. |
| `send_payment` | Money out under an `ACTIVE` SEND contract. |
| `get_payment` | Read one payment. |
| `list_payments` | Filter by `type`, `status`, contract, or customer. |
| `cancel_payment` | Cancel an unpaid collect. |

### Refunds

| Tool | Purpose |
| - | - |
| `refund_payment` | Refund a `COMPLETED` collect, full or partial. |
| `list_refunds` | All refunds on a payment. |
| `cancel_refund` | Cancel a pending refund. |

### Customers & stores

| Tool | Purpose |
| - | - |
| `create_customer` · `get_customer` · `list_customers` · `update_customer` · `delete_customer` | Manage customers (page `list_customers` to find one by name/email). |
| `list_stores` | Discover your business locations. Tool-driven payments always use the primary store. |

## Approvals: the human stays in charge

There is no approval tool. When `send_payment` or an off-session `collect_payment` returns a `nextAction`, show
`nextAction.approvalUrl` to the right person and wait for their decision — the business owner for a payout, the
customer for a charge. The model can't approve its own payment, and the one-time code or passkey is only ever
entered on Atoa's page.

Every payment an agent makes is a normal `Payment` — `list_payments` and `get_payment` give it (and you) the full
audit trail.

## No AI required

The tools are a thin layer over the SDK. Without a model in the loop, call the same operations directly —
`atoa.payment.collect(...)`, `atoa.payment.send(...)` — for identical behaviour.

## Prefer MCP?

The hosted [Atoa MCP server](https://docs.paywithatoa.com/mcp-server.md) exposes Atoa's tools to Claude, Cursor, VS Code, and any other
MCP-compatible client — no SDK integration needed.

## Rendering results

Tool results that need a human — a pay-link, a contract authorisation, an approval — carry a
[`nextAction`](https://docs.paywithatoa.com/agent-pay/next-action). Pass that action to `AtoaUI.mount()` in a web UI with
[embedded checkout](https://docs.paywithatoa.com/agent-pay/embed.md), or post `nextAction.fallback.text` in a text channel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.