# Agent Bank API

Institutional wallet service. Signs x402 payments on your behalf after a human verifies their identity. All endpoint paths are relative to the base URL this document is served from.

## Quick start

```
cat .agent-bank-auth-token
```

If the file exists, skip to **Making payments**. If not, start with **Enrollment**.

---

## Enrollment

### 1. Start enrollment

```
POST /api/v1/agent_connect
```

No body, no auth. Returns a `token` and a `kyc_url`.

### 2. Save the token

```
echo "{token}" > .agent-bank-auth-token
```

### 3. Present kyc_url to the human

Tell the user to open `kyc_url` in their browser. **Do not open it yourself.** Wait for them to say they are done.

### 4. Confirm enrollment

```
GET /api/v1/agent_connect/status
Authorization: Bearer {token}
```

`"status": "active"` means you are ready. `401` means the human has not finished.

---

## Making payments

### Option A: One-shot (bank proxies the request)

```
POST /api/v1/payments/pay
Authorization: Bearer {token}
Content-Type: application/json

{ "url": "http://merchant/resource" }
```

The bank fetches the URL, handles the 402, signs, retries, and returns the result.

### Option B: Three-step (you control the merchant request)

**Step 1** — GET the merchant URL. A 402 response body contains JSON payment requirements.

**Step 2** — Forward the 402 body to the bank:

```
POST /api/v1/payments/pay/x402
Authorization: Bearer {token}
Content-Type: application/json

{ "merchant_url": "...", "payment_requirements": {402 JSON body} }
```

`payment_requirements` is the JSON object, not a string.

**Step 3** — If `"status": "signed"`, retry the merchant:

```
GET {merchant_url}
X-Payment: {x_payment_header from step 2}
```

If `"status": "pending_approval"`, present `approval_url` to the user and poll `wallet_check_approval_status` until the status changes to `approved`, then retry with the same idempotency key.

---

## Approval flow

All payments require human approval before they are signed.

### Step 1 — Submit payment

Use `wallet_pay_url`. If the payment requires approval, the response will include `status: "pending_approval"` and an `approval_url`.

### Step 2 — Present the approval URL to the human

Tell the user to open the approval URL in their browser and approve or deny the payment.

### Step 3 — Poll for approval

```
wallet_check_approval_status { "transaction_id": "..." }
```

Returns `pending_approval`, `approved`, `declined`, or `expired`. Poll every few seconds until the status changes.

### Step 4 — Complete the payment

Once approved, re-call `wallet_pay_url` with the **same idempotency key**. The payment will be signed and the authorization returned.

If denied or expired, inform the user. The payment can be re-initiated with a new idempotency key.