Okx Agent Payments Protocol

# a2a_charge — agent-to-agent payment links (`onchainos payment a2a-pay`)

> Loaded from `../SKILL.md` when the user mentions a paymentId, an `a2a_...` link, "create payment link", or asks to check a2a payment status. Unlike the HTTP 402 paths (`accepts`-based and `WWW-Authenticate: Payment`), a2a is **not triggered by an HTTP 402 response** — it's invoked by name, with a paymentId or a seller's create-link request.

Wraps `onchainos payment a2a-pay` end-to-end for both seller and buyer roles. Buyer-side trust is **delegated to the upstream caller** — when invoked with a `paymentId`, the skill fetches the on-server challenge, TEE-signs it as-is, submits the credential, and auto-polls payment status to a terminal state.

## Pre-flight

Both seller (`create`) and buyer (`pay`) require an authenticated wallet session. Before invoking either:

```bash
onchainos wallet status
```

- **Logged in** → proceed.
- **Not logged in** → ask the user to log in via `onchainos wallet login` (AK login, no email) or `onchainos wallet login <email>` (OTP login). **Do NOT attempt to sign without a live session.**

`status` does not require additional pre-flight beyond what the CLI itself enforces.

---

## Seller — Create a Payment Link

**Inputs**:
- **Required**: `--amount` (decimal, e.g. `"0.01"`), `--symbol` (e.g. `"USDT"`), `--recipient` (0x... EVM address — seller wallet)
- **Optional**: `--description`, `--realm`, `--expires-in` (seconds, default 1800)

**Steps**:

1. Run pre-flight (see above).
2. Shell out:
   ```bash
   onchainos payment a2a-pay create \
     --amount <amount> --symbol <symbol> --recipient <recipient> \
     [--description <text> --realm <domain> --expires-in <seconds>]
   ```
3. Parse the response — only `payment_id` and `deliveries.url` (optional) are present. The CLI no longer returns `amount` / `currency`; echo the seller's input args back for display.
4. Display:

   > Payment link created.
   > • paymentId: `<id>`
   > • Amount: `<amount input> <symbol input>` (decimal as you submitted)
   > • Recipient: `<recipient input>`
   > • Share with buyer: `<deliveries.url>` (if returned by the server) or `paymentId=<id>`

5. Suggest next: poll status anytime with `onchainos payment a2a-pay status --payment-id <id>` once the buyer is expected to have paid.

---

## Buyer — Pay a Payment Link

**Required input**: `paymentId` only. The CLI fetches the seller-issued challenge from the server and signs whatever amount / currency / recipient the challenge declares.

> **Trust model**: the buyer signs the seller's challenge as-is. Verifying that the challenge matches what the buyer agreed to pay is the **upstream caller's responsibility** — the user (or the upstream skill) MUST cross-check the seller's `paymentId` / `deliveries.url` against their out-of-band agreement (chat, task spec, prior negotiation) **before** calling this skill. Once invoked, the skill signs whatever the on-server challenge declares.

### Step 1 — Sign and submit

The skill does not run its own preview / yes-no gate; trust is delegated upstream. Shell out directly:

```bash
onchainos payment a2a-pay pay --payment-id <paymentId>
```

The CLI fetches the on-server challenge, TEE-signs the EIP-3009 authorization, and submits the credential. Two outcomes:

**Accepted** — `ok:true`, exit code 0:

```json
{
  "ok": true,
  "data": {
    "payment_id":   "a2a_xxx",
    "status":       "<status>",
    "tx_hash":      "<hash or null>",
    "valid_after":  0,
    "valid_before": 1746000000,
    "signature":    "0x..."
  }
}
```

Proceed to Step 2 (auto-poll).

**Rejected** — server returned `data.success:false` (e.g. `errorReason:"insufficient_balance"`). CLI surfaces it as a hard failure: `ok:false`, exit code 1, message embeds the reason verbatim:

```json
{
  "ok": false,
  "error": "payment a2a_xxx rejected (reason=<errorReason>)"
}
```

**Treat as terminal — do NOT retry `pay`.** Every retry produces a fresh EIP-3009 nonce + signature; if the reason is `insuffi