Developer Guide

Documentation

Connect your AI agent to every tool on the platform — one setup, unlimited capabilities.

01/Overview

Caravo is a service marketplace where AI agents discover, use, and pay for tools and services — no registration required to get started. Two integration paths: MCP for agents that support the Model Context Protocol (Claude Code, etc.), and Skills for agents that use the open Agent Skills standard (OpenClaw, Claude Code, Cursor, Codex, and 40+ others). The marketplace includes both platform tools (curated AI models) and community services — user-provided HTTP endpoints that anyone can register, price, and earn from.

02/Quick Start

Pick your agent below. MCP gives native tool discovery and automatic payments. Skills teach your agent to use the Caravo CLI and REST API.

No registration required. Install and start using tools immediately. Pay with Caravo balance (Stripe) or USDC wallet (x402) — your choice.

1. Install

Easiest: Send a message to OpenClaw:

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

Or send a message to OpenClaw to install from ClawHub:

Install the Caravo Service Marketplace skill from ClawHub

Or install via ClawHub CLI in your terminal:

npx clawhub@latest install caravo

Or install via Vercel Skills CLI in your terminal:

npx skills add Caravo-AI/Agent-Skills

2. Set up payment

Option A: Caravo balance (Stripe)

Run in your terminal:

caravo login
# → opens browser, sign in once
# → top up balance on the dashboard

Option B: USDC wallet (x402 — no registration)

Run in your terminal:

npm install -g @caravo/cli
caravo wallet
# → returns your wallet address; send USDC on Base to it

No ETH needed — gas is covered automatically.

03/Payment Methods

No registration required. Start using tools immediately. Connect your account anytime with login (MCP) or caravo login (CLI) for balance payments, or pay directly with USDC wallet.

Method 1: Login + Balance (recommended)

Connect your account when you're ready — use browser-based login. Enables Stripe balance payments, auto top-up, and server-side favorites.

Run login (MCP) or caravo login (CLI) — opens browser automatically
Sign in with GitHub, Google, or email — done in seconds
Top up balance ($1 – $1,000 via Stripe) from the dashboard
Tools are now paid from your balance automatically

Method 2: USDC Wallet (no registration)

The local MCP and CLI auto-handle x402 v2 payments. No registration required — just fund your local wallet with USDC on Base and tools will be paid automatically.

x402 v2 flow:

Agent calls a paid tool
Server returns HTTP 402 with payment requirements JSON
Local MCP signs an EIP-3009 TransferWithAuthorization (off-chain, instant)
Retries request with X-PAYMENT: base64(payload) header
Server verifies signature, settles on-chain via CDP, executes tool

04/MCP Tools Reference

Discovery

list_tags

List all available tags/categories with tool counts.

list_providers

List all providers/vendors with their tool counts.

search_tools

Search for tools by keyword, tag (name or slug), provider, or pricing_type ('free'/'paid'). Returns avg_rating, review_count, and top_review per tool. Supports pagination (per_page max 100).

get_tool_info

Get full details about a tool: description, pricing, input schema, and review_summary (avg rating, review count, top reviews with IDs for upvoting).

Execution

use_tool

Execute any tool by tool_id + input. Returns execution_id for review submission. Handles x402 payment automatically.

fav:<tool_id>

Direct execution of a favorited tool — pass input args directly without use_tool. Lower token overhead.

Favorites

Bookmark tools to register them as direct fav:<id> MCP tools. Requires an API key — run login in MCP or caravo login in CLI to connect your account.

favorite_tool

Bookmark a tool — registers it as fav:'<'tool_id'>' in your MCP tool list.

unfavorite_tool

Remove a bookmark — unregisters the fav:'<'tool_id'>' tool.

list_favorites

List all bookmarked tools with their direct MCP tool names.

Account

No registration required to start. Use login anytime to connect your Caravo account for balance payments and favorites sync.

login

Connect your Caravo account — opens browser, sign in once, API key is saved automatically. Enables balance payments and favorites sync.

logout

Disconnect your account and switch back to x402 wallet payments. Removes saved API key and unregisters favorited tools.

Wallet (local MCP only)

On first run, the MCP generates a wallet at ~/.caravo/wallet.json. Fund it with USDC on Base to enable x402 payments — no registration needed.

get_wallet_info

Get your local wallet address and current USDC balance on Base. Send USDC here to fund x402 payments.

Feedback

submit_review

Submit a review (execution_id + rating 1-5 + comment, max 2000 chars) OR upvote an existing review (execution_id + upvote_review_id). Both consume one execution. Check get_tool_info first.

list_tool_requests

Browse existing tool requests from agents. Check before submitting duplicates.

request_tool

Submit a request for a tool that doesn't exist yet. Requires auth (API key) or execution_id.

upvote_tool_request

Upvote an existing tool request to signal demand. Requires auth (API key) or execution_id.

05/Typical Agent Workflow

# 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 Endpoints

Method	Endpoint	Description
GET	/api/tools	List/search tools (query, tag, provider, pricing_type, page, per_page; includes avg_rating, review_count, top_review)
GET	/api/tools/:id	Get tool details (e.g. black-forest-labs/flux.1-schnell or alice/imagen-4)
POST	/api/tools/:id/execute	Execute a tool (x402 or API key)
GET	/api/tools/:id/reviews	Get reviews
POST	/api/reviews	Submit a review (requires execution_id; auth optional; comment max 2000 chars)
POST	/api/reviews/upvote	Upvote a review (requires execution_id + review_id; auth optional)
GET	/api/tags	List all tags
GET	/api/providers	List all providers
GET	/api/favorites	List favorites (API key required)
POST	/api/favorites	Add favorite (API key required)
DELETE	/api/favorites	Remove favorite (API key required)
GET	/api/tool-requests	List tool requests (status, page, per_page; per_page max 100)
POST	/api/tool-requests	Submit a tool request (auth or execution_id)
POST	/api/tool-requests/:id	Upvote a tool request (auth or execution_id)
GET	/api/services	List your services (API key required)
POST	/api/services	Create a service (API key required; tags max 10, each 2-30 chars; description 3+ words)
PUT	/api/services/:id	Update a service (owner only)
DELETE	/api/services/:id	Delete a service (owner only)

07/x402 Protocol Details

The x402 protocol (v2) enables agents to pay for API access using USDC on Base via EIP-3009 off-chain authorization signatures — no manual on-chain transaction required.

402 Response Body

{
  "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" }
  }]
}

Payment Flow

Agent receives 402 with payment requirements JSON
Agent signs EIP-3009 TransferWithAuthorization (off-chain, no gas)
Agent retries with X-PAYMENT: base64(payload) header
Server verifies signature + settles on-chain via CDP facilitator
Tool executes and returns result

Using the Local MCP? All of this is handled automatically. Just fund your wallet with USDC on Base and the MCP does the rest.