# @buysign/x402

내 서버를 x402 로 팔리게 만든다. **미들웨어 한 줄.**

```bash
npx create-x402-store my-store
cd my-store
# .env 의 PAY_TO 에 돈 받을 지갑 주소를 넣는다
npm install && npm run dev
curl -i http://localhost:8787/hello.txt     # → 402 Payment Required
```

402 가 뜨면 끝났다. 그 다음이 결제다.

## 파는 쪽 (Express · Next.js API route)

```js
import { x402 } from "@buysign/x402/express";

app.get("/report.pdf",
  x402({ price: "0.50", payTo: "0x...", networks: ["eip155:4663"] }),
  (req, res) => {
    // 결제가 끝난 뒤에만 실행된다
    res.locals.x402;          // { order_id, transaction, payer, ... }
    res.sendFile("/report.pdf");
  });
```

## 프레임워크 없이

```js
import { createStore } from "@buysign/x402";

const store = createStore({ payTo: "0x...", networks: ["eip155:4663"] });
const { status, body, headers } = await store.handle({
  url, price: "0.50", paymentHeader: req.headers["x-payment"],
});
```

`(status, body, headers)` 만 돌려준다. Workers·Fastify·Hono 어디든 붙는다.

## 구매자는 가스를 내지 않는다

EIP-3009 는 **서명과 체인 제출을 분리**한다. 구매자는 "이 금액을 이 주소로" 에
서명만 하고, 체인에 올려 가스를 내는 건 판매자 쪽 릴레이어다.
구매자 지갑에는 스테이블코인만 있으면 된다.

## 지원 레일

| 네트워크 | 자산 | EIP-712 도메인 |
|---|---|---|
| `eip155:4663` Robinhood Chain | USDG `0x5fc5…1d168` | `Global Dollar` / `1` |
| `eip155:8453` Base | USDC `0x8335…2913` | `USD Coin` / `2` |

도메인 `name`/`version` 은 온체인 `DOMAIN_SEPARATOR()` 와 대조해 확정한 값이다.
새 레일을 넣을 땐 추측하지 마라 — 틀리면 "서명자 불일치" 로만 보여서 디버깅이 어렵다.

## 동작 규약

**가격이 없으면 402 를 만들지 않는다.** `price` 없이 부르면 예외가 난다.
임의 금액을 요구하는 402 는 나가지 않는다.

**같은 nonce 로 두 번 팔지 않는다.** 에이전트는 재시도한다. 같은 nonce 면 같은 주문을
돌려준다. 체인도 nonce 재사용을 막지만, 체인에 닿기 전 단계에서도 막는다.

**검증 없이 200 을 주지 않는다.** 퍼실리테이터 `verify` → `settle` 을 거친 뒤에만
주문이 생긴다.

## CLI

```bash
npx x402 quote    <url>                 402 응답과 결제 조건을 본다
npx x402 test-buy <url> --max 1.00      한도 안인지까지 확인한다
```

실제 결제(서명)는 키를 가진 클라이언트로 한다:
```bash
pip install x402-bind
x402-bind new && x402-bind buy <url> --max 1.00
```

## 아직 없는 것

- **에스크로 없음.** 결제가 즉시 판매자에게 이전된다.
- **Node 구매자 SDK 없음.** 서명이 로컬에서 일어나야 해서 파이썬으로 먼저 냈다.

MIT · 문서 https://buysign.ai/docs