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)

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.

---