# AI로 연동하기 · blockwallets

> 직접 코드를 쓰지 않고 blockwallets 암호화폐 결제를 추가하세요. 사이트와 AI 도구를 고르고, 생성된 프롬프트를 Claude Code, Codex, Cursor, ChatGPT에 붙여 넣으면 문서를 보고 연동하고 스스로 점검합니다.
>
> HTML: https://blockwallets.io/docs/ai?lang=ko · English: https://blockwallets.io/docs/ai.md?lang=en

## 범용 프롬프트

```text
blockwallets로 제 웹사이트에서 암호화폐 결제를 받을 수 있게 도와주세요(고객은 USDT, USDC, BTC 등으로 결제하고, 저는 미국 달러로 정산받습니다).

1. API를 추측하지 말고 먼저 문서를 읽으세요: https://blockwallets.io/llms-full.txt(전체 문서)와 https://blockwallets.io/agents.md(연동 규칙, 흔한 실수, 인수 체크리스트). 열 수 없으면 알려 주세요.
2. 제 프로젝트를 살펴보고 무엇으로 만들어졌는지, 어떻게 연동할 계획인지 알려 준 다음 제 승인을 기다리세요.
3. 기본은 “청구서를 만들어 결제 페이지로 이동 + 웹훅”입니다. 웹훅 서명은 항상 검증하고, 같은 웹훅이 두 번 올 수 있으니 중복을 제거하세요.
4. merchant ID와 API key는 환경 변수에 두고, 먼저 테스트넷의 Test 자격 증명으로 동작하게 만드세요.
5. 끝나면 agents.md의 인수 체크리스트를 항목별로 확인하고 결과를 알려 주세요.

저는 프로그래머가 아닙니다. 단계마다 무엇을 고쳤는지, 제가 무엇을 해야 하는지 알려 주세요.
```

## 내 사이트를 알려 주세요.

잘 모르겠다면 “기타 / 잘 모르겠음”을 고르세요. AI가 먼저 프로젝트를 살펴봅니다.

- 사이트를 만든 방식: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · 기타 / 잘 모르겠음
- 결제를 받는 방식:
  - 결제 페이지로 이동: 결제 단계에서 청구서를 만들고, 결제가 끝나면 서버로 알려 드립니다. 주문은 알아서 발송됩니다.
  - 사용자마다 고정 입금 주소: 사용자마다 영구 주소가 생기고, 언제든 원하는 금액을 충전합니다.
  - 결제 링크 (코드 없음): 관리 화면에서 링크를 만들어 공유합니다. AI는 버튼만 추가합니다.

결제 링크는 코드가 필요 없습니다. 관리 화면 → “결제 › 결제 링크” → 금액 입력 → 만들기, 그다음 링크를 공유하세요. AI는 사이트에 버튼만 추가합니다.

## 어떤 AI를 쓰세요?

- **Claude Code / Codex**: 코드를 고치고 명령을 실행하는 AI. 가장 쉽습니다.
  - 웹사이트 프로젝트 폴더에서 터미널을 열고 연동 규칙을 AGENTS.md로 저장하세요.
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex는 AGENTS.md를 알아서 읽습니다. Claude Code라면 아래도 실행하세요.
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - 그런 다음 3단계의 프롬프트를 붙여 넣으세요.
  - blockwallets MCP 서버를 설치하면 AI가 문서를 검색하고 테스트 청구서를 직접 만들 수도 있습니다. https://blockwallets.io/docs/mcp?lang=ko
- **Cursor / Windsurf / Copilot**: 코드 에디터 안의 AI.
  - AGENTS.md를 프로젝트 루트에 두세요(Cursor가 자동으로 읽습니다).
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Agent 모드로 바꾸고 프롬프트를 붙여 넣으세요.
  - blockwallets MCP 서버를 설치하면 AI가 문서를 검색하고 테스트 청구서를 직접 만들 수도 있습니다. https://blockwallets.io/docs/mcp?lang=ko
- **ChatGPT / Claude (웹)**: 대화만 가능합니다. 코드는 직접 사이트에 붙여 넣어야 합니다.
  - 새 대화에 프롬프트를 붙여 넣거나 아래의 “ChatGPT / Claude에서 열기”를 쓰세요.
  - 링크를 열 수 없다고 하면 https://blockwallets.io/llms-full.txt를 열어 전체를 선택해 복사한 다음 이것도 붙여 넣으세요.
  - 완성된 코드와 둘 위치를 알려 줍니다. 단계별로 따라 하세요. 코드를 대신 고쳐 주는 도구(Claude Code, Codex, Cursor)를 쓰면 복사해 붙이는 수고가 크게 줄어듭니다.
- **다른 AI**: Gemini, Copilot 채팅 등.
  - 프롬프트를 붙여 넣으세요. 웹 페이지를 열 수 없다면 llms-full.txt의 내용도 함께 붙여 넣으세요.

## 프롬프트를 복사하세요.

위에서 고른 내용에 따라 바뀌며, 문서 링크와 흔한 함정, 인수 체크리스트가 들어 있습니다.

예시: 기타 / 잘 모르겠음 + 결제 페이지로 이동 + Claude Code / Codex

```text
당신은 제 개발자입니다. blockwallets로 제 웹사이트에서 암호화폐 결제를 받을 수 있게 도와주세요(고객은 USDT, USDC, BTC와 다른 14가지 코인으로 결제하고, 저는 미국 달러로 정산받습니다).

## 제 상황
- 제 사이트는 다음으로 만들어졌습니다: 잘 모르겠습니다. 먼저 제 프로젝트를 살펴보고 무엇으로 만들어졌는지 알려 준 다음 시작해 주세요.
- 결제를 받고 싶은 방식: 결제 단계에서 청구서를 만들어 고객을 blockwallets 결제 페이지로 보내 주세요. 돈이 도착하면 blockwallets가 제 서버를 호출하고, 저는 주문을 결제 완료로 표시하고 발송합니다.
- 저는 프로그래머가 아닙니다. 단계마다 어떤 파일을 고쳤는지, 제가 무엇을 해야 하는지(예: 환경 변수를 어디에 두는지) 알려 주세요. 한 번에 너무 많이 바꾸지 마세요.
- 프로젝트 루트의 AGENTS.md에 blockwallets 연동 규칙이 있으니 먼저 읽고, 자세한 내용은 https://blockwallets.io/llms-full.txt를 읽어 주세요.

## 먼저 문서를 읽으세요. API를 기억에 의존해 추측하지 마세요
- 전체 연동 문서(Markdown): https://blockwallets.io/llms-full.txt
- 연동 규칙과 흔한 실수: https://blockwallets.io/agents.md
- 이미 Cryptomus, NOWPayments, Coinbase Commerce를 쓰는 사이트라면 새로 짜지 말고 해당하는 호환 API로 바꿔 주세요: https://blockwallets.io/docs/migrate.md?lang=en
- 링크를 열 수 없다면 알려 주세요. 제가 내용을 붙여 넣겠습니다.

## 핵심 사항 (연동에서 흔히 틀리는 부분)
1. 모든 엔드포인트는 https://blockwallets.io의 POST + JSON입니다. 헤더: merchant = 가맹점 UUID, sign = md5(base64(요청 본문) + API key). 보내는 JSON 문자열 그대로 서명하고, 서명한 뒤에 다시 직렬화하지 마세요.
2. POST /v1/payment로 청구서를 만드세요. 필수: amount(소수점 둘째 자리까지의 문자열, 예: "42.00"), currency("USD"), order_id(제 주문 번호: 영문자, 숫자, -, _, 100자 이하). url_callback(웹훅 URL)과 url_success(결제 후 고객이 돌아올 주소)도 함께 넘기세요. 고객을 result.url로 보내세요.
3. 같은 order_id로 다시 호출하면 같은 청구서를 돌려주므로 재시도해도 안전하고 청구서가 두 개 생기지 않습니다.
4. 웹훅 서명은 반드시 검증하세요. 웹훅 JSON을 파싱하고 sign 필드를 제거한 뒤 나머지를 PHP json_encode와 같은 방식으로 다시 인코딩합니다(공백 없이, 비 ASCII 문자는 그대로, /는 \/로 이스케이프). 그러고 나서 md5(base64(인코딩한 문자열) + API key)가 sign과 같아야 합니다. /를 이스케이프하지 않는 것이 가장 흔한 실수입니다.
5. status가 paid 또는 paid_over일 때만 payment_amount_usd 기준으로 주문을 결제 완료 처리하세요. 같은 웹훅이 두 번 이상 올 수 있으니 uuid + status로 중복을 제거하세요. 처리가 끝나면 2xx 상태로 응답하세요.
6. merchant ID와 API key는 환경 변수(예: BW_MERCHANT, BW_API_KEY)에 두고, 코드에 직접 쓰거나 커밋하지 마세요. 먼저 관리 화면의 “개발자 › 연동 및 키” 페이지에서 “웹사이트 도메인”에 웹훅 URL의 도메인을 추가해야 합니다.
7. 먼저 Test 자격 증명(테스트넷, 실제 돈 없음)으로 모든 것이 동작하게 만드세요. Live 전환은 제가 확인한 뒤에만 하세요.

## 끝나면 항목마다 확인하고 결과를 알려 주세요
- [ ] Test 자격 증명으로 테스트 청구서를 만들고 결제 페이지 링크(result.url)를 받는다
- [ ] 결제 페이지를 열고 “결제 시뮬레이션” → 전액을 누른다
- [ ] 서버가 status가 paid인 웹훅을 받고 서명이 검증된다
- [ ] 해당 주문이 결제 완료로 표시된다
- [ ] 같은 웹훅이 다시 와도(관리 화면 “개발자 › 웹훅 로그”에서 다시 보내거나 POST /v1/payment/resend) 두 번 발송되지 않는다

실패한 항목이 있으면 다른 것을 고치기 전에, 어디서 막혔는지와 정확한 오류 메시지를 알려 주세요.
```

### AI가 끝나면 이것을 확인하세요

**결제 페이지로 이동**

1. Test 자격 증명으로 테스트 청구서를 만들고 결제 페이지 링크(result.url)를 받는다
2. 결제 페이지를 열고 “결제 시뮬레이션” → 전액을 누른다
3. 서버가 status가 paid인 웹훅을 받고 서명이 검증된다
4. 해당 주문이 결제 완료로 표시된다
5. 같은 웹훅이 다시 와도(관리 화면 “개발자 › 웹훅 로그”에서 다시 보내거나 POST /v1/payment/resend) 두 번 발송되지 않는다

**사용자마다 고정 입금 주소**

1. Test 자격 증명으로 테스트 사용자의 주소를 만들고 주소와 입금 페이지 링크를 받는다
2. POST /v1/test-webhook/wallet로 샘플 웹훅을 보낸다
3. 서버가 type이 wallet인 웹훅을 받고 서명이 검증된다
4. 그 사용자의 잔액이 payment_amount_usd만큼 늘어난다
5. 같은 웹훅이 다시 와도 잔액이 두 번 늘지 않는다

**결제 링크 (코드 없음)**

1. 버튼이 데스크톱과 휴대폰에서 모두 알맞게 보인다
2. 버튼이 제 결제 링크를 연다(먼저 Test 모드에서 만든 링크로)
3. 결제 페이지에서 “결제 시뮬레이션”을 누르면 관리 화면의 “결제 › 결제 내역”에 그 결제가 보인다

## AI가 막혔을 때.

- **서명이 계속 검증되지 않아요**: 받은 웹훅 본문 원문을 [서명 검사기](https://blockwallets.io/docs/sign?lang=ko)에 붙여 넣으세요. 모든 중간 단계를 보여 주고 처음 달라지는 곳을 표시합니다. 무엇이 다른지 그대로 AI에게 알려 주세요.
- **엔드포인트가 오류를 돌려줘요**: 요청과 응답을 message까지 정확히 그대로 AI에게 붙여 넣으세요. 서명이 틀리면 401 응답의 debug.body_base64가 저희가 서명한 텍스트이니, AI가 자기 결과와 비교하게 하세요.
- **어디서 막혔는지 모르겠어요**: AI에게 인수 체크리스트를 첫 항목부터 하나씩 확인하고 항목별 결과를 알려 달라고 하세요. 관리 화면의 “개발자 › 웹훅 로그”에서 모든 웹훅 요청과 서버의 응답을 볼 수 있습니다.

### 직접 챙길 네 가지.

- **AI에게는 Test 자격 증명만 주세요**: Test merchant ID와 API key는 테스트넷에서 동작하므로 유출되어도 돈이 움직이지 않습니다.
- **Live API key는 대화에 넣지 마세요**: Live API key는 직접 서버의 환경 변수에 넣으세요. 대화에 붙여 넣거나 저장소에 커밋하지 마세요.
- **AI가 고치기 전에 백업하세요**: AI가 시작하기 전에 사이트 파일을 커밋(git commit)하거나 복사해 두세요. 되돌릴 수 있습니다.
- **라이브 전에 직접 한 번 결제해 보세요**: Live로 전환한 뒤 관리 화면 홈의 “한 건 시험 결제”로 소액을 실제로 결제해, 주문이 결제 완료로 바뀌고 잔액이 들어오는지 확인하세요.

## 코딩 에이전트용 규칙 파일.

AGENTS.md에는 연동의 핵심, 흔한 실수, 인수 체크리스트가 들어 있습니다. 프로젝트 루트에 두세요. Codex와 Cursor는 자동으로 읽고, Claude Code는 @AGENTS.md로 불러옵니다.

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [연동 규칙 (AGENTS.md)](https://blockwallets.io/agents.md)
- [한 페이지 요약](https://blockwallets.io/llms.txt)
- [전체 문서](https://blockwallets.io/llms-full.txt)
- [이 페이지의 Markdown](https://blockwallets.io/docs/ai.md?lang=ko)
- [문서의 Markdown](https://blockwallets.io/docs.md?lang=ko)
- [MCP 서버](https://blockwallets.io/docs/mcp?lang=ko)

## 궁금한 점, 답해 드립니다.

### 코딩을 못 해도 정말 AI로 연동할 수 있나요?

대부분의 사이트는 가능합니다. AI가 문서를 보고 청구서 생성과 서명 코드를 작성하고, 당신은 자격 증명을 환경 변수에 넣은 다음 테스트 모드에서 인수 체크리스트를 따라 확인하면 됩니다. 코드를 아예 쓰고 싶지 않다면 결제 링크를 쓰세요.

### 어떤 AI 도구를 써야 하나요?

프로젝트를 직접 고치고 명령을 실행하는 도구가 가장 쉽습니다: Claude Code, Codex, Cursor. 웹의 ChatGPT나 Claude도 되지만 코드를 직접 사이트에 붙여 넣어야 합니다.

### AI에게 API key를 줘도 되나요?

Test 자격 증명만, 그것도 대화가 아니라 환경 변수 파일에 넣어서 주세요. Live API key는 직접 서버에 넣으세요.

### 웹훅 서명이 계속 검증되지 않아요. 어떻게 하죠?

sign을 제거하고 나머지를 PHP json_encode처럼 다시 인코딩하되 /를 \/로 이스케이프하세요. 받은 웹훅 본문 원문을 /docs/sign에 붙여 넣어 모든 단계를 비교한 다음, 무엇이 다른지 AI에게 알려 주세요.

### AI가 다 했다고 하는데 어떻게 확인하나요?

인수 체크리스트를 실행하세요: 테스트 청구서를 만들고, 결제를 시뮬레이션하고, 웹훅이 검증되는지, 주문이 결제 완료로 바뀌는지 보고, 같은 웹훅을 다시 보내 두 번 발송되지 않는지 확인합니다. 라이브 전에 Live로 소액을 결제해 보세요.