# Signet Agent API — Skill Reference

> **Base URL:** `https://www.sig17z.com/api` (e.g. `http://localhost:3141/api`)
> **Auth:** `Authorization: Bearer sig_<your-api-key>`
> **Money:** USDG on Robinhood Chain (id 4663), decimal strings, max 6 dp.

Signet is peer-to-peer USDG payments where AI agents transact autonomously
inside limits their human set. You get your own on-chain hot wallet; the
server signs your sends only while they pass policy: per-payment cap, rolling
24h cap, pause switch, and your live on-chain balance as the hard ceiling.

## Quick start

```bash
# 1. Register (your human gives you a one-time pairing token)
curl -X POST https://www.sig17z.com/api/auth/register/agent \
  -H "Content-Type: application/json" \
  -d '{"pairingToken": "<token>", "displayName": "my-agent"}'
# → { "user": {...}, "apiKey": "sig_..." }   SAVE THE KEY — shown once.

# 2. Check your wallet and allowance
curl https://www.sig17z.com/api/wallets/me -H "Authorization: Bearer $KEY"

# 3. Pay someone
curl -X POST https://www.sig17z.com/api/transfers/send \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"toUsername": "alice", "amount": "0.50", "memo": "api credits"}'
```

## Pairing flow

1. Your human clicks **Pair agent** on their dashboard, sets your caps, and
   gets a one-time token (15-minute expiry).
2. You call `POST /auth/register/agent` with it. You receive your `@username`,
   wallet address, and API key.
3. Your human funds your wallet (USDG allowance + a sliver of ETH for gas).
4. You transact until a cap, a pause, or your balance stops you. Your human
   can sweep or revoke you at any time — expect it, handle 401/403 gracefully.

## Endpoints

### POST /auth/register/agent — no auth
Body: `pairingToken` (required), `displayName` (optional `[a-z0-9_]{3,20}`).
201 → `{ user, apiKey, warning }`. 401 if the token is used/expired.

### GET /wallets/me
Your address, USDG/ETH balances, owner, `paused`, and `limits`
(`perTxMicro`, `dailyMicro`, `spentTodayMicro`, `remainingTodayMicro`).
Micro = USDG × 10⁶.

### POST /transfers/send
Body: `toUsername` or `toAddress`, `amount` (decimal string), `memo?`.
201 → `{ transfer, txHash, explorer }` after on-chain confirmation.
403 with `code` when policy rejects:

| code | meaning |
|---|---|
| `PER_TX_LIMIT` | amount exceeds your per-payment cap (see `limitMicro`) |
| `DAILY_LIMIT` | would exceed the rolling 24h cap (see `remainingMicro`) |
| `INSUFFICIENT_FUNDS` | your wallet balance is the hard ceiling |
| `PAUSED` / `REVOKED` | your human hit the switch |

### POST /transfers/request
Ask someone to pay you: `{ from, amount, memo? }` → 201 `{ request }`.

### GET /transfers/requests/incoming
Requests waiting for YOU to pay → `{ requests: [...] }`.

### POST /transfers/requests/:id/accept
Pays the request from your wallet (same policy as any send) → `{ request, txHash }`.

### POST /transfers/requests/:id/dismiss
Decline a request → `{ request }`.

### GET /transactions?cursor&limit
Your transfer history, newest first → `{ transactions, nextCursor }`.

### POST /keys/rotate
New API key (returned once); the old key is dead the moment this returns.

### POST /webhooks · GET /webhooks · DELETE /webhooks/:id
Register up to 5 endpoints: `{ url, events }` where `events` is `"*"` or a
csv of: `transfer.sent transfer.received transfer.confirmed request.created
request.paid request.dismissed agent.paused agent.revoked`.
201 returns `secret` once.

## Webhook signatures

Every delivery is signed. Verify before trusting:

```
X-Signet-Timestamp: 1757500000
X-Signet-Signature: sha256=<hex>
```

```js
const expected = "sha256=" + crypto
  .createHmac("sha256", secret)
  .update(`${req.headers["x-signet-timestamp"]}.${rawBody}`)
  .digest("hex");
// timing-safe compare with X-Signet-Signature; reject stale timestamps (>5 min)
```

Deliveries retry 5 times with exponential backoff (1s → 81s).

## Ground rules

- Amounts are strings, never floats. `"0.50"`, max 6 decimal places.
- Rate limit: 30 sends/min. Back off on 429.
- You cannot: withdraw to arbitrary chains, touch your human's wallet,
  raise your own limits, or manage friends. Humans keep the controls.
- Every send lands on the public explorer: be a good citizen, your history
  is your reputation.