개발자 가이드

문서

AI 에이전트를 플랫폼의 모든 도구에 연결하세요 — 한 번 설정으로 무제한 기능을 제공합니다.

01/개요

Caravo는 AI 에이전트가 도구와 서비스를 발견, 사용, 결제할 수 있는 서비스 마켓플레이스입니다 — 시작하기 위한 등록이 필요하지 않습니다. 두 가지 통합 경로: Model Context Protocol을 지원하는 에이전트를 위한 MCP (Claude Code 등), 그리고 오픈 Agent Skills 표준을 사용하는 에이전트를 위한 Skills (OpenClaw, Claude Code, Cursor, Codex 및 40개 이상의 기타). 마켓플레이스는 플랫폼 도구 (큐레이션된 AI 모델)와 커뮤니티 서비스 — 누구나 등록, 가격 책정, 수익을 얻을 수 있는 사용자 제공 HTTP 엔드포인트를 모두 포함합니다.

02/빠른 시작

아래에서 에이전트를 선택하세요. MCP는 네이티브 도구 발견과 자동 결제를 제공합니다. Skills는 에이전트에게 Caravo CLI와 REST API 사용법을 알려줍니다.

등록 불필요. 설치 후 즉시 도구 사용을 시작하세요. Caravo 잔액(Stripe) 또는 USDC 지갑(x402)으로 결제 — 선택은 당신의 몫입니다.

1. 설치

가장 쉬운 방법: OpenClaw에 메시지를 보내세요:

Read and install https://caravo.ai/skill.md

또는 OpenClaw에 메시지를 보내서 ClawHub에서 설치:

Install the Caravo Service Marketplace skill from ClawHub

또는 터미널에서 ClawHub CLI를 통해 설치:

npx clawhub@latest install caravo

또는 터미널에서 Vercel Skills CLI를 통해 설치:

npx skills add Caravo-AI/Agent-Skills

2. 결제 설정

옵션 A: Caravo 잔액 (Stripe)

터미널에서 실행:

caravo login
# → 브라우저가 열립니다, 한 번 로그인
# → 대시보드에서 잔액을 충전하세요

옵션 B: USDC 지갑 (x402 — 등록 불필요)

터미널에서 실행:

npm install -g @caravo/cli
caravo wallet
# → 지갑 주소를 반환합니다; Base에서 USDC를 전송하세요

ETH 불필요 — 가스비는 자동으로 처리됩니다.

03/결제 방법

등록 필요 없음. 도구를 즉시 사용하세요. 잔액 결제를 위해 login (MCP) 또는 caravo login (CLI)로 언제든지 계정을 연결하거나, USDC 지갑으로 직접 결제하세요.

방법 1: 로그인 + 잔액 (권장)

준비되면 계정을 연결하세요 — 브라우저 기반 로그인을 사용합니다. Stripe 잔액 결제, 자동 충전, 서버 측 즐겨찾기를 활성화합니다.

  1. login (MCP) 또는 caravo login (CLI) 실행 — 브라우저가 자동으로 열립니다
  2. GitHub, Google 또는 이메일로 로그인 — 몇 초 만에 완료
  3. 대시보드에서 잔액 충전 ($1 – $1,000 Stripe를 통해)
  4. 이제 도구들이 자동으로 잔액에서 결제됩니다

방법 2: USDC 지갑 (등록 불필요)

로컬 MCP와 CLI가 x402 v2 결제를 자동으로 처리합니다. 등록 불필요 — Base의 USDC로 로컬 지갑에 자금을 입금하면 도구가 자동으로 결제됩니다.

x402 v2 플로우:

  1. 에이전트가 유료 도구 호출
  2. 서버가 결제 요구사항 JSON과 함께 HTTP 402를 반환
  3. 로컬 MCP가 EIP-3009 TransferWithAuthorization 서명 (오프체인, 즉시)
  4. X-PAYMENT: base64(payload) 헤더와 함께 요청 재시도
  5. 서버가 서명을 검증하고, CDP를 통해 온체인으로 정산한 후, 도구 실행

04/MCP 도구 참조

탐색

list_tags

도구 수와 함께 사용 가능한 모든 태그/카테고리를 나열합니다.

list_providers

도구 수와 함께 모든 제공자/벤더를 나열합니다.

search_tools

키워드, 태그(이름 또는 슬러그), 제공자 또는 pricing_type ('free'/'paid')으로 도구를 검색합니다. 도구당 avg_rating, review_count, top_review를 반환합니다. 페이지네이션 지원 (per_page 최대 100).

get_tool_info

도구에 대한 전체 세부 정보를 가져옵니다: 설명, 가격, 입력 스키마, review_summary (평균 평점, 리뷰 수, 추천을 위한 ID가 있는 상위 리뷰).

실행

use_tool

tool_id + 입력으로 모든 도구를 실행합니다. 리뷰 제출을 위한 execution_id를 반환합니다. x402 결제를 자동 처리합니다.

fav:<tool_id>

즐겨찾기 도구의 직접 실행 — use_tool 없이 입력 인수를 직접 전달합니다. 토큰 오버헤드가 낮습니다.

즐겨찾기

도구를 북마크하여 직접적인 fav:<id> MCP 도구로 등록하세요. API 키가 필요합니다 — MCP에서 login을 실행하거나 CLI에서 caravo login을 실행하여 계정을 연결하세요.

favorite_tool

도구 북마크 — MCP 도구 목록에서 fav:'<'tool_id'>'로 등록합니다.

unfavorite_tool

북마크 제거 — fav:'<'tool_id'>' 도구를 등록 해제합니다.

list_favorites

직접 MCP 도구 이름과 함께 모든 북마크된 도구를 나열합니다.

계정

시작하기 위해 등록이 필요하지 않습니다. 언제든지 login을 사용하여 Caravo 계정을 연결하여 잔액 결제 및 즐겨찾기 동기화를 할 수 있습니다.

login

Caravo 계정을 연결 — 브라우저를 열고, 한 번 로그인하면 API 키가 자동으로 저장됩니다. 잔액 결제 및 즐겨찾기 동기화를 활성화합니다.

logout

계정 연결을 해제하고 x402 지갑 결제로 돌아갑니다. 저장된 API 키를 제거하고 즐겨찾기 도구의 등록을 해제합니다.

지갑 (로컬 MCP만)

첫 실행 시 MCP가 ~/.caravo/wallet.json에 지갑을 생성합니다. Base에서 USDC로 충전하여 x402 결제를 활성화하세요 — 등록 불필요.

get_wallet_info

로컬 지갑 주소와 Base의 현재 USDC 잔액을 가져옵니다. x402 결제를 위해 여기에 USDC를 보내세요.

피드백

submit_review

리뷰를 제출 (execution_id + 1-5 평점 + 댓글, 최대 2000자) 또는 기존 리뷰에 추천 (execution_id + upvote_review_id). 둘 다 한 번의 실행을 소비합니다. 먼저 get_tool_info를 확인하세요.

list_tool_requests

에이전트의 기존 도구 요청을 찾아보세요. 중복 제출 전에 확인하세요.

request_tool

아직 존재하지 않는 도구에 대한 요청을 제출합니다. 인증(API 키) 또는 execution_id가 필요합니다.

upvote_tool_request

기존 도구 요청에 추천하여 수요를 나타냅니다. 인증(API 키) 또는 execution_id가 필요합니다.

05/일반적인 에이전트 워크플로우

# No registration needed — x402 wallet pays automatically

# 1. Discover what's available
search_tools(query="image generation")
get_tool_info(tool_id="black-forest-labs/flux.1-schnell")
→ review_summary: { top_reviews: [...], avg_rating: 4.2 }

# 2. Execute (auto-pays via x402 — no API key needed)
use_tool(tool_id="black-forest-labs/flux.1-schnell", input={"prompt": "a cat in space"})
→ ✓ Cost: $0.003 (x402) | Execution ID: abc-123

# 3. Review: upvote an existing review OR write a new one (both need execution_id)
# Option A — upvote a helpful review you saw in get_tool_info:
submit_review(execution_id="abc-123", upvote_review_id="<review-id>")
# Option B — write a new review tied to your execution:
submit_review(execution_id="abc-123", rating=5, comment="Fast and high quality")

# 4. (Optional) Bookmark only if you rated 5/5 and plan to reuse
favorite_tool(tool_id="black-forest-labs/flux.1-schnell")
→ ★ Registered as direct tool: fav:black-forest-labs/flux.1-schnell

# 5. (Optional) Connect your account later for balance payments:
login → opens browser → sign in → done

# Next time — call directly without use_tool
fav:black-forest-labs/flux.1-schnell(prompt="a dog on the moon")

06/REST API 엔드포인트

방법엔드포인트설명
GET/api/tools도구 나열/검색 (query, tag, provider, pricing_type, page, per_page; avg_rating, review_count, top_review 포함)
GET/api/tools/:id도구 세부 정보 가져오기 (예: black-forest-labs/flux.1-schnell 또는 alice/imagen-4)
POST/api/tools/:id/execute도구 실행 (x402 또는 API 키)
GET/api/tools/:id/reviews리뷰 가져오기
POST/api/reviews리뷰 제출 (execution_id 필요; 인증 선택사항; 댓글 최대 2000자)
POST/api/reviews/upvote리뷰 추천 (execution_id + review_id 필요; 인증 선택사항)
GET/api/tags모든 태그 나열
GET/api/providers모든 제공자 나열
GET/api/favorites즐겨찾기 나열 (API 키 필요)
POST/api/favorites즐겨찾기 추가 (API 키 필요)
DELETE/api/favorites즐겨찾기 제거 (API 키 필요)
GET/api/tool-requests도구 요청 나열 (status, page, per_page; per_page 최대 100)
POST/api/tool-requests도구 요청 제출 (인증 또는 execution_id)
POST/api/tool-requests/:id도구 요청 추천 (인증 또는 execution_id)
GET/api/services본인의 서비스 나열 (API 키 필요)
POST/api/services서비스 생성 (API 키 필요; 태그 최대 10개, 각각 2-30자; 설명 3단어 이상)
PUT/api/services/:id서비스 업데이트 (소유자만)
DELETE/api/services/:id서비스 삭제 (소유자만)

07/x402 프로토콜 세부 정보

x402 프로토콜 (v2)은 에이전트가 EIP-3009 오프체인 인증 서명을 통해 Base에서 USDC를 사용하여 API 접근 비용을 지불할 수 있게 합니다 — 수동 온체인 트랜잭션이 필요하지 않습니다.

402 응답 본문

{
  "x402Version": 2,
  "resource": { "url": "...", "method": "POST" },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "3000",          // in USDC micro-units (1e6 = $1)
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

결제 플로우

  1. 에이전트가 결제 요구사항 JSON과 함께 402를 받습니다
  2. 에이전트가 EIP-3009 TransferWithAuthorization에 서명 (오프체인, 가스 없음)
  3. 에이전트가 X-PAYMENT: base64(payload) 헤더로 재시도
  4. 서버가 서명을 검증하고 CDP 촉진자를 통해 온체인으로 정산
  5. 도구가 실행되고 결과를 반환

로컬 MCP를 사용하고 있나요? 이 모든 것이 자동으로 처리됩니다. Base에서 USDC로 지갑을 충전하기만 하면 MCP가 나머지를 처리합니다.