> For the complete documentation index, see [llms.txt](https://docs.netauthpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.netauthpay.com/agents/agent-usage.md).

# Agent Usage

This section is for developers building autonomous agents that use NetAuth.

#### Capabilities

* **Register** once per agent to get a wallet.
* **Check balance** before sending.
* **Send** single or batch payments with optional memo and metadata.
* **Query** payment status and history (only for payments you’re involved in).

#### Base URL

Use your NetAuth server URL, e.g. `http://localhost:3000` or `https://netauth.yourdomain.com`.

#### Minimal integration example (TypeScript)

```typescript
const BASE = 'http://localhost:3000';

async function registerAgent(agentId: string) {
  const res = await fetch(`${BASE}/api/agents/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ agentId }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function getBalance(agentId: string) {
  const res = await fetch(`${BASE}/api/agents/${agentId}/balance`);
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function sendPayment(
  from: string,
  to: string,
  amountLamports: number,
  memo?: string,
  metadata?: Record<string, string>
) {
  const res = await fetch(`${BASE}/api/payments/send`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fromAgentId: from, toAgentId: to, amount: amountLamports, memo, metadata }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function sendBatch(
  from: string,
  payments: Array<{ toAgentId: string; amount: number; memo?: string; metadata?: Record<string, string> }>
) {
  const res = await fetch(`${BASE}/api/payments/send-batch`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fromAgentId: from, payments }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function getPaymentHistory(agentId: string, limit?: number, offset?: number, status?: string) {
  const params = new URLSearchParams();
  if (limit != null) params.set('limit', String(limit));
  if (offset != null) params.set('offset', String(offset));
  if (status) params.set('status', status);
  const url = `${BASE}/api/payments/agent/${agentId}${params.toString() ? '?' + params : ''}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}
```

#### Best practices

* **Register once** and store `agentId` and `publicKey`.
* **Check balance** before sending; handle insufficient balance errors.
* **Treat payments as async**: after `POST /send` or `POST /send-batch`, poll `GET /api/payments/:paymentId?agentId=...` or use history to confirm completion.
* **Store payment IDs** when you send so you can check status later.
* **Use metadata** for your own IDs (invoices, tasks) so you can reconcile payments in your system.
* **Handle errors** and non-2xx responses; respect rate limits in production.

***
