--- title: "게스트ウォ렛" description: "계정 없이 TwexAPI 키를 받아보세요: AI 에이전트가 Stripe 카드 체크아웃을 생성하고, 사람이 그것을 지불하면 키는 모든 엔드포인트와 MCP에서 작동합니다." --- # 게스트ウォ렛 게스트ウォ렛은 계정, 가입 또는 이메일이 필요 없는 предоплаченная TwexAPI API 키입니다. AI 에이전트가 한 번의 요청으로 지갑을 생성하고 API 키와 Stripe 체크아웃 링크를 반환합니다. 사람이 카드로 링크를 지불하면 키는 모든 TwexAPI 엔드포인트와 MCP 서버에서 작동합니다. 계정 키와 같습니다. :::warning 게스트ウォ렛은 항상 사람이 지불해야 합니다. 에이전트가 체크아웃을 생성하고 링크를 제공하지만, 카드 정보는 입력되지 않습니다. 사용자가 금액을 확인한 후에만 지갑을 생성하세요. ::: ## 접근 방법 선택 | 방법 | 계정 | 자격 증명 | 커버리지 | 지불 | |---|---|---|---|---| | [계정 API 키](/ko/authentication) | 예 | `Authorization: Bearer ` | 모든 엔드포인트와 MCP | 대시보드: 카드, PayPal 또는 크립토 | | [MCP 로그인](/ko/mcp/oauth) | 예 | MCP 클라이언트에서 OAuth | MCP 도구 | 계정의 Credits | | 게스트ウォ렛 | 아니요 | `Authorization: Bearer <게스트 키>` | 모든 엔드포인트와 MCP | 카드, Stripe Checkout을 통해 예치금 | | [MPP](/ko/mpp/machine-payments-protocol) | 아니요 | `Authorization: Payment <자격 증명>` | 12 개의 페이징된 읽기 엔드포인트 | Tempo에서 USDC, 요청 당 | Use a guest wallet when an agent needs a normal API key for a person who doesn't want an account. Use MPP when the agent has its own wallet and pays per request. Use an account key for anything long-lived. ## 지갑 생성 및 활성화 **1. 금액 확인.** 지갑은 USD 10에서 250까지, `amount_minor`로 cent로 전송됩니다 (`1000`에서 `25000`까지). Credits는 100,000 Credits per USD의 표준 비율로 추가되며, USD 10은 1,000,000 Credits를 구매합니다. [가격](/ko/guides/pricing)을 참조하여 요청이 얼마나 드는지 확인하세요. **2. 체크아웃 생성.** `Idempotency-Key` 헤더에 새 UUID v4를 보내세요: ```bash curl -sS https://api.twexapi.io/guest-wallets \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \ -d '{"amount_minor": 1000, "currency": "usd"}' ``` ```json { "code": 200, "msg": "success", "data": { "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c", "api_key": "twitterx_...", "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...", "checkout_expires_at": "2026-10-29T14:21:01.000Z", "status_url": "/guest-wallets/status", "poll_after_seconds": 5, "purchase": { "id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "kind": "create", "status": "pending", "amount_minor": 1000, "currency": "usd", "credits": 1000000 } } } ``` **3. 키 저장.** 즉시 `api_key`를 비밀 저장소에 저장하세요. 이는 지갑의 유일한 자격 증명이며, TwexAPI는 그것을 복구할 수 없습니다. **4. 사용자에게 체크아웃 링크 제공.** `checkout_url`를 사용자에게 보여주고 지불을 요청하세요. 링크는 한 번 사용 가능하며 60분 후에 만료됩니다. 지불이 확인되지 않을 때까지 API 호출은 `401`을 반환합니다. **5. 키 사용 가능까지 대기.** `poll_after_seconds` 간격으로 호출을 반복하세요: ```bash curl -sS https://api.twexapi.io/guest-wallets/status \ -H "Authorization: Bearer $GUEST_KEY" ``` ```json { "code": 200, "msg": "success", "data": { "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c", "key_hint": "twitterx_1a2…9f0e", "usable": true, "paused": false, "available_credits": 1000000, "latest_purchase": { "kind": "create", "status": "completed", "credits": 1000000 }, "poll_after_seconds": null } } ``` `usable`가 `true`가 되면 API를 호출하시기 시작하세요. 완료된 체크아웃 페이지만으로 Credits가 추가된 것을 의미하지 않습니다. `latest_purchase.status`는 지불이 확인되면 `completed`가 됩니다. 미지불된 체크아웃은 `expired`가 되고, 거절된 지연된 지불은 `failed`가 됩니다. `poll_after_seconds`는 더 이상 대기할 것이 없을 때 `null`이 됩니다. ## API 호출 사용 가능한 게스트 키는 모든 엔드포인트에서 작동하며, 계정 키와 같은 제한 조건과 청구 조건을 가집니다: ```bash curl -sS https://api.twexapi.io/twitter/advanced_search/page \ -H "Authorization: Bearer $GUEST_KEY" \ -H "Content-Type: application/json" \ -d '{"searchTerms": ["openai"], "sortBy": "Latest"}' ``` Credits가 소진되면 요청은 `403`으로 `No available credits!`를 반환합니다. 지갑을 충전하여 계속하세요. ## 지갑 충전 충전은 Credits를 동일한 지갑과 키에 추가합니다. 사용자와 다시 금액을 확인한 후 새 UUID v4를 보내세요: ```bash curl -sS https://api.twexapi.io/guest-wallets/topups \ -H "Authorization: Bearer $GUEST_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \ -d '{"amount_minor": 2000, "currency": "usd"}' ``` 응답에는 새 `checkout_url`가 포함됩니다. 사용자에게 링크를 제공하고, `latest_purchase.status`가 `completed`가 되까지 동일한 상태 엔드포인트를 호출하여 확인하세요. ## 키 없이 요청 TwexAPI 엔드포인트에 자격 증명이 없는 요청은 `403`으로 `WWW-Authenticate: Bearer realm="twexapi"` 헤더를 반환합니다. 일반적인 `code`, `msg`, `data` 필드에 이어 `auth_options` 객체가 추가되어 접근 방법을 나열합니다. 게스트ウォ렛 생성을 포함하여: ```json { "code": 403, "msg": "Not authenticated", "data": [], "auth_options": { "account": { "scheme": "Bearer", "dashboard": "https://twexapi.io/dashboard" }, "guest_wallet": { "method": "POST", "url": "https://api.twexapi.io/guest-wallets", "idempotency_header": "Idempotency-Key", "body": { "amount_minor": 1000, "currency": "usd" }, "amount_minor_min": 1000, "amount_minor_max": 25000, "status_url": "https://api.twexapi.io/guest-wallets/status" }, "pay_per_request": { "scheme": "Payment", "endpoints": ["POST /twitter/advanced_search/page", "..."] }, "mcp": { "url": "https://api.twexapi.io/mcp", "pay_per_call_url": "https://api.twexapi.io/mcp/pay" }, "docs": "https://twexapi.io/llms.txt" } } ``` `auth_options`는 에이전트가 무엇이 가능한지 알려줍니다. 이는 돈을 지출하는 허가가 아니며, 에이전트는 여전히 사용자가 지갑을 생성하기 전에 금액에 동의해야 합니다. ## MCP와 게스트 키 사용 지갑이 사용 가능하면 MCP 클라이언트를 `https://api.twexapi.io/mcp`에 연결하여 게스트 키를 `Authorization: Bearer` 헤더에 포함하여, [MCP 개요](/ko/mcp/overview)에 설명된대로 사용하세요. 지갑 생성, 충전 및 상태 확인은 REST 만이 가능합니다; 이에 대한 MCP 도구는 없습니다. ## 오류 | 상태 | 의미 | 무엇을 해야 합니까 | |---|---|---| | `400` | `Idempotency-Key`가 누락되었거나 유효하지 않거나, `amount_minor`가 1000에서 25000 범위를 벗어났거나, `usd`가 아닌 다른 통화 | 요청을 수정하세요 | | `401` | 베어러 키가 누락되었거나 게스트ウォ렛 키가 아닙니다 | 단계 2에서 게스트 키를 전송하세요 | | `403` | 지갑이 중지되었습니다 | 지원에 연락하세요 | | `409` | 재시도된 체크아웃 요청이 만료되기 전에 너무 가까워 완료할 수 없습니다 | 새 `Idempotency-Key`로 재시도하세요 | | `422` | `Idempotency-Key`가 다른 요청에 이미 사용되었습니다 | 새 UUID v4를 사용하세요 | | `429` | 1시간 동안 하나의 IP 주소에서 많은 지갑이 생성되었습니다 | 대기하고 재시도하세요 | ## 일관성 및 안전한 재시도 모든 생성 및 충전 요청은 독립적인 UUID v4가 필요합니다. 요청이 시간이 걸리면 동일한 키로 변경되지 않은 요청을 다시 보내세요: 원래 결과가 `Idempotent-Replayed: true` 헤더로 표시되며, 두 번째 체크아웃은 없습니다. 다른 금액이나 다른 요청에 키를 재사용하면 `422`이 반환됩니다. ## 지갑 접근 보호 - 게스트 키와 `Idempotency-Key` 값을 URL, 로그 및 채팅 트랜스크립트에서 유지하세요. 생성 요청의 `Idempotency-Key`를 재사용하면 API 키가 다시 반환됩니다. - 응답은 `Cache-Control: no-store, private`로 전송됩니다.缓存하지 마세요. - 상태 엔드포인트에서 `usable`를 기반으로 API를 호출하기 전에 체크아웃 페이지를 기반으로 하지 마세요. - 지불이 분쟁되면 전체 지갑이 중지되고 (`paused: true`) 키가 작동하지 않습니다. 분쟁이 해결될 때까지 기다려야 합니다. ## 자주 묻는 질문 ### TwexAPI Twitter API를 계정 없이 사용할 수 있나요? 네. 게스트ウォ렛은 가입 없이 예치금 TwexAPI 키를 제공하며, [MPP](/ko/mpp/machine-payments-protocol)는 에이전트가 Tempo 지갑을 가지고 있으면 요청 당 지불할 수 있습니다. ### AI 에이전트는 TwexAPI를 자체로 지불할 수 있나요? 아니요. 게스트ウォ렛은 항상 사람이 Stripe 체크아웃을 지불해야 합니다. 에이전트가 자체 USDC를 가지고 있는 경우 [MPP](/ko/mpp/machine-payments-protocol)를 통해 요청 당 지불할 수 있습니다. ### 게스트 키는 일부 엔드포인트에 제한되나요? 아니요. 지불이 완료되면 게스트 키는 모든 엔드포인트와 MCP 서버에서 작동하며, 계정 키와 같은 가격과 제한 조건을 가집니다. ### 게스트ウォ렛을 나중에 계정으로 변환할 수 있나요? 아니요. 지금은 게스트 키를 계속 사용하고 충전하거나, 새로운 작업을 위해 계정을 생성하고 그 키를 사용하세요. ## 다음 단계 - [인증](/ko/authentication)을 통해 계정 API 키 - [마이크로 페이먼츠 프로토콜](/ko/mpp/machine-payments-protocol)를 통해 요청 당 접근 - [MCP 개요](/ko/mcp/overview)을 통해 AI 클라이언트에서 키 사용 - [가격](/ko/guides/pricing)을 통해 Credit 비용 확인