# Uniple x402 Agent Skill

Skill + MCP server for AI agents buying products exposed through Uniple's x402
catalog API. It is intended for KOVA, Codex, Claude Desktop, and other MCP-capable
agent clients.

This is separate from `jpyc-ec-purchase`: JPYC EC uses x402 v2,
`POST /api/v1/checkout`, and `PAYMENT-SIGNATURE`. Uniple currently uses
x402 v1, catalog/payment URLs, and `X-PAYMENT`.

## What It Supports

- Read-only catalog discovery:
  - `GET https://uniple.io/api/x402/shop/eccube/products?merchantSiteId=...`
- Quote / payment challenge:
  - `GET paymentUrl` with `quantity` and `shipping*` query params
  - Reads `402` + decoded `paymentRequired`
- Optional purchase:
  - Signs JPYC EIP-3009 `TransferWithAuthorization`
  - Calls the same payment URL with `X-PAYMENT`
  - Returns Uniple's paid response and webhook status

## Safety

Use `quote_product` first. It never signs or sends funds.

`purchase_product` requires:

- `BUYER_PRIVATE_KEY` env var
- `max_amount_atomic` budget cap
- matching quote amount within that cap

Do not configure a funded private key unless you intend to allow the MCP server
to purchase.

## Local Build

```bash
cd uniple-x402-agent-skill
npm install
npm run build
npm test
```

## MCP Config Example

```json
{
  "mcpServers": {
    "uniple-x402-purchase": {
      "command": "node",
      "args": [
        "/absolute/path/uniple-x402-agent-skill/mcp-servers/uniple-x402-purchase/dist/bin.js"
      ],
      "env": {
        "UNIPLE_API_URL": "https://uniple.io",
        "BUYER_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

Omit `BUYER_PRIVATE_KEY` if you only want catalog and quote tools.

## EC-CUBE4 Smoke Target

Catalog:

```text
https://uniple.io/api/x402/shop/eccube/products?merchantSiteId=eccube4.uniple.io
```

Typical 55 JPYC item quote with the current EC-CUBE4 shipping settings:

- product subtotal: 55 JPYC
- shipping: 150 JPYC
- total: 205 JPYC
- network: `eip155:137`
- asset: JPYC Polygon `0xE7C3...3c29`