OpenOcean
GitHub
AI Agents

AI Agents — Skills

OpenOcean Skills is an open-source plugin for AI coding assistants (Cursor, Claude Code, OpenClaw). Use natural-language commands for quotes, transaction builds, and on-chain execution. This page covers setup, the four skills, and recommended API endpoints for agent integration.

OpenOcean-skills (GitHub)

Overview

There are four skills, designed to be used from safest to fastest. quote and swap-build only need GET requests and work out of the box. swap-execute and swap-execute-fast require Foundry and wallet configuration for on-chain broadcasting.

Project Structure

Skills live under skills/, while shared API docs and token data live under references/.

Project Structure
openocean-skills/
├── skills/
│ ├── quote/# Get a swap quote
│ │ └── SKILL.md
│ ├── swap-build/# Build swap calldata (with confirmation)
│ │ └── SKILL.md
│ ├── swap-execute/# Execute a swap via Foundry cast (with confirmation)
│ │ └── SKILL.md
│ ├── swap-execute-fast/# Build and execute in one step (no confirmation)
│ │ ├── SKILL.md
│ │ └── scripts/
│ │ ├── fast-swap.sh# Token resolution and route building
│ │ └── execute-swap.sh# Calls fast-swap.sh and then broadcasts
│ └── error-handling/# Troubleshooting and error codes
│ └── SKILL.md
├── references/# Shared docs
│ ├── api-reference.md
│ └── token-registry.md
├── test/# Prompt test cases
│ └── agent-test-cases.md# English test prompts
└── README.md

Installation

This repo works with Cursor, Claude Code, OpenClaw, and other mainstream tools.

Download the repo, either as a ZIP archive or via git clone, and place it in your tool's skills directory.

After extraction, make sure the project root still contains the references/ folder, since the skills read token-registry.md and api-reference.md from there.

Prerequisites & Availability

  • Reference files: Skills read references/token-registry.md and references/api-reference.md from the workspace root. Ensure these files are present.
  • Quote / Build: quote and swap-build only require the ability to send GET requests, such as mcp_web_fetch or curl; no local installation is needed.
  • Execute: swap-execute and swap-execute-fast require Foundry (cast) plus RPC and wallet configuration.

If something goes wrong, check:

  1. Correct workspace with references/;
  2. API requests use integer-string amountDecimals (no decimal point);
  3. User-facing slippage 100 means 100 bps = 1%, while the API parameter uses percent (1 = 1%);
  4. Foundry is installed and ETH_RPC_URL plus any required wallet settings are configured for on-chain execution.

Skills Overview

quote

Get the best swap route and price for a token pair.

Terminal
TXT
1
/quote 1 ETH to USDC on ethereum
2


3
/quote 100 USDC to WBTC on arbitrum
4


5
/quote 0.5 WBTC to DAI on polygon

Returns: expected output amount, USD value, exchange rate, estimated gas, and route path (DEXes used).

swap-build

Build a full swap transaction, including the route and encoded calldata. Requires a sender address. Shows quote details such as rate, minimum output, and gas, then asks for confirmation before building.

Terminal
TXT
1
/swap-build 100 USDC to ETH on arbitrum from 0xYourAddress
2


3
/swap-build 1 ETH to USDC on ethereum from 0xYourAddress slippage 100

Returns: encoded calldata, router address, transaction value, gas estimate, minimum output after slippage. Does not submit on-chain.

swap-execute

Execute a previously built swap on-chain using Foundry's cast send. Consumes swap-build output and broadcasts it.

Terminal
TXT
1
/swap-execute

Requires Foundry (cast). Supports multiple wallet options, including environment variables, Ledger, Trezor, or a keystore. Asks for confirmation before execution because the transaction is irreversible.

swap-execute-fast

Build and execute a swap in one step, with no confirmation prompt.

Terminal
TXT
1
/swap-execute-fast 1 ETH to USDC on base from 0xYourAddress
2


3
/swap-execute-fast 100 USDC to ETH on arbitrum from 0xYourAddress keystore mykey
4


5
/swap-execute-fast 0.5 WBTC to DAI on polygon from 0xYourAddress ledger

Requires cast, curl, and jq. Extremely dangerous: builds and executes immediately with no confirmation. Use only when you fully trust the parameters and understand the risks.

Recommended endpoints

  • Quote — GET quote for a given in/out token and amount; use to show users expected output before executing.
  • Swap — POST to get transaction calldata; agent or user signs and broadcasts. Always quote first, then swap with the same params plus account.
  • Token list — GET supported tokens for a chain to resolve symbols to addresses and decimals.

Rate limits and retries

Public tier: 2 RPS (20 requests per 10 seconds). Implement exponential backoff on 429 and 5xx. For agents that need higher throughput, request an API key or Enterprise plan.

State and errors

Handle errors explicitly: 400 (bad params), 404 (unsupported token/chain), 429 (rate limit), 5xx (retry with backoff). Always confirm transaction status on-chain after sending; do not assume success from API response alone.

Next Steps

AI Agents Overview

Full AI integration guide.

Swap API Overview

Quote and Swap endpoints.

Swagger UI

Try endpoints interactively.