게스트ウォ렛

계정 없이 TwexAPI 키를 받아보세요: AI 에이전트가 Stripe 카드 체크아웃을 생성하고, 사람이 그것을 지불하면 키는 모든 엔드포인트와 MCP에서 작동합니다.

게스트ウォ렛

게스트ウォ렛은 계정, 가입 또는 이메일이 필요 없는 предоплаченная TwexAPI API 키입니다. AI 에이전트가 한 번의 요청으로 지갑을 생성하고 API 키와 Stripe 체크아웃 링크를 반환합니다. 사람이 카드로 링크를 지불하면 키는 모든 TwexAPI 엔드포인트와 MCP 서버에서 작동합니다. 계정 키와 같습니다.

접근 방법 선택

지갑 생성 및 활성화

1. 금액 확인. 지갑은 USD 10에서 250까지, amount_minor로 cent로 전송됩니다 (1000에서 25000까지). Credits는 100,000 Credits per USD의 표준 비율로 추가되며, USD 10은 1,000,000 Credits를 구매합니다. 가격을 참조하여 요청이 얼마나 드는지 확인하세요.

2. 체크아웃 생성. Idempotency-Key 헤더에 새 UUID v4를 보내세요:

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"}'

{
  "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 간격으로 호출을 반복하세요:

curl -sS https://api.twexapi.io/guest-wallets/status \
  -H "Authorization: Bearer $GUEST_KEY"

{
  "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 호출

사용 가능한 게스트 키는 모든 엔드포인트에서 작동하며, 계정 키와 같은 제한 조건과 청구 조건을 가집니다:

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를 보내세요:

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 객체가 추가되어 접근 방법을 나열합니다. 게스트ウォ렛 생성을 포함하여:

{
  "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 개요에 설명된대로 사용하세요. 지갑 생성, 충전 및 상태 확인은 REST 만이 가능합니다; 이에 대한 MCP 도구는 없습니다.

오류

일관성 및 안전한 재시도

모든 생성 및 충전 요청은 독립적인 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는 에이전트가 Tempo 지갑을 가지고 있으면 요청 당 지불할 수 있습니다.

AI 에이전트는 TwexAPI를 자체로 지불할 수 있나요?

아니요. 게스트ウォ렛은 항상 사람이 Stripe 체크아웃을 지불해야 합니다. 에이전트가 자체 USDC를 가지고 있는 경우 MPP를 통해 요청 당 지불할 수 있습니다.

게스트 키는 일부 엔드포인트에 제한되나요?

아니요. 지불이 완료되면 게스트 키는 모든 엔드포인트와 MCP 서버에서 작동하며, 계정 키와 같은 가격과 제한 조건을 가집니다.

게스트ウォ렛을 나중에 계정으로 변환할 수 있나요?

아니요. 지금은 게스트 키를 계속 사용하고 충전하거나, 새로운 작업을 위해 계정을 생성하고 그 키를 사용하세요.

다음 단계

• 인증을 통해 계정 API 키
• 마이크로 페이먼츠 프로토콜를 통해 요청 당 접근
• MCP 개요을 통해 AI 클라이언트에서 키 사용
• 가격을 통해 Credit 비용 확인