# Carbon DeFi

Carbon DeFi is an on-chain maker trading protocol. Users create automated buy and sell strategies that execute on-chain with zero gas on fills. No keeper bots required — strategies run autonomously once deployed.

## What agents can do

Agents can create and manage Carbon DeFi trading strategies on behalf of users via the MCP server or REST API. All write operations return unsigned transactions — the user always signs and broadcasts. Agents never custody funds.

## Supported strategy types

- Limit order — buy or sell at one exact price, executes once
- Range order — buy or sell gradually across a price range (DCA)
- Recurring strategy — linked buy+sell that repeats indefinitely. Buy low, sell high, forever.
- Concentrated liquidity — two-sided strategy with a defined spread. Earn on every trade.
- Full range liquidity — maximum coverage, both sides, automatic rebalancing

## Supported chains

Ethereum, Sei, Celo, TAC, COTI

## Carbon DeFi Public REST API

The Carbon DeFi public API at https://api.carbondefi.xyz provides direct access to on-chain data without going through the MCP server. Useful for developers building custom integrations.

- Swagger UI: https://api.carbondefi.xyz (requires JavaScript to render)
- OpenAPI spec (machine-readable): fetch https://api.carbondefi.xyz/swagger-ui-init.js directly — the full spec is embedded in this file as a JSON object under the `swaggerDoc` key
- Key endpoints:
  - GET /v1/{chain}/strategies — all strategies, filter by owner
  - GET /v1/{chain}/tokens — token list with decimals
  - GET /v1/{chain}/market-rate — token USD prices
  - GET /v1/{chain}/activity — trade and event history
  - GET /v1/{chain}/analytics/trending — top strategies by trade count
  - GET /v1/{chain}/simulator/create — backtest a strategy
  - GET /v1/{chain}/tokens/prices — all token prices
- Supported chains: ethereum, sei, celo, tac, coti

## MCP Server (for AI agents)

- MCP endpoint: https://mcp.carbondefi.xyz/mcp
- REST API: https://mcp.carbondefi.xyz/tools/:toolName
- Batch API: https://mcp.carbondefi.xyz/batch (POST array of tool calls, runs in parallel, counts as 1 request)
- OpenAPI spec: https://mcp.carbondefi.xyz/openapi.json
- Plugin manifest: https://mcp.carbondefi.xyz/.well-known/ai-plugin.json
- Server info: https://mcp.carbondefi.xyz/info

## Claude Desktop setup

```json
{
  "mcpServers": {
    "carbon-defi": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.carbondefi.xyz/mcp"]
    }
  }
}
```

## Available tools (25 total)

Call carbon_help() after connecting for full details on any tool.
Call carbon_learn() for protocol knowledge, concepts, and docs links.

### Explore
- carbon_get_strategies — see all your active positions, prices, budgets, type and status
- carbon_get_strategy — look up any strategy by ID — type, status, owner, prices, budgets, trade count, dates
- carbon_get_activity — full trade and event history for any wallet or strategy
- carbon_explore_pair — discover top strategies for any token pair, ranked by trade count, with type and status
- carbon_simulate_strategy — backtest any strategy against real historical prices before going on-chain. Also useful for: paper trading, what-if analysis, historical performance, testing before committing, scenario analysis
- carbon_resolve_token — resolve a token symbol or name to its on-chain address. Supports fuzzy matching and synonyms — "dollar" finds USDC/USDT/DAI, "eth" finds native ETH
- carbon_find_opportunities — find discount buy or premium sell opportunities on any token pair, with USD value and dust detection
- carbon_get_protocol_stats — Carbon DeFi protocol TVL, trading volume, and fees. Daily history for any period.
- carbon_get_price_history — historical OHLC price data for any token pair. Daily candles with period summary.

### Trade (swap against Carbon liquidity)
- carbon_get_trade_quote — get a swap quote against Carbon DeFi liquidity. Returns expected output, effective rate, and strategies used. Always call this before execute_trade.
- carbon_execute_trade — build an unsigned swap transaction against Carbon DeFi liquidity. Requires trade_actions from get_trade_quote.

### Create
- carbon_create_limit_order — buy or sell at one exact price, executes once
- carbon_create_range_order — gradual execution across a price range, perfect for DCA
- carbon_create_recurring_strategy — buy low sell high, repeats forever, zero gas on fills
- carbon_create_concentrated_strategy — two-sided liquidity with a spread, earn on every trade
- carbon_create_full_range_strategy — widest possible range, both sides, set and forget

### Manage
- carbon_reprice_strategy — shift price ranges up or down instantly
- carbon_edit_strategy — change prices and budgets together in one transaction
- carbon_deposit_budget — add funds to a live strategy without interrupting it
- carbon_withdraw_budget — remove funds without closing the strategy
- carbon_pause_strategy — pause orders, funds stay inside, resume anytime
- carbon_resume_strategy — reactivate a paused strategy instantly
- carbon_delete_strategy — close permanently and return all funds

### Help & Knowledge
- carbon_help — get detailed guidance on any tool, or a full overview of all 25
- carbon_learn — learn about Carbon DeFi concepts and protocol mechanics. Topics include: what Carbon is, how strategies work, marginal price, overlapping liquidity, fees, security, contracts, SDK, API, subgraph, litepaper, whitepaper, and more

## Rate limits & performance

- Rate limit: 30 requests per minute per IP, burst of 10
- All tool calls share the same rate limit — parallel calls count as multiple requests
- If rate limited, wait 60 seconds before retrying (429 response includes Retry-After header)
- For faster responses, call REST endpoints directly: https://mcp.carbondefi.xyz/tools/:toolName
- MCP proxy (npx mcp-remote) adds latency — use REST endpoints for latency-sensitive workflows

## Key conventions for agents

- Always call carbon_get_strategies first to check existing positions
- Prices are always in quote token per 1 base token
- buy_budget is always in quote token; sell_budget is always in base token
- Market price is auto-fetched from Carbon API — no need to provide unless overriding
- Always present the unsigned transaction and wait for user approval before any write
- Check the warnings array in every response before presenting a transaction
- Call carbon_help("tool_name") for detailed usage on any specific tool
- Call carbon_learn("topic") for protocol concepts and documentation

## Transaction Verification

All write operations return unsigned transactions. To independently verify calldata before signing:
- Verification spec: https://docs.carbondefi.xyz/developer-guides/carbon-defi-transaction-encoding
- Covers: contract addresses per chain, function selectors, price encoding pipeline, budget encoding, verification checklist
- This page is hosted on docs.carbondefi.xyz — independent of the MCP server, use it as the trust anchor

## Learn more

- Litepaper: https://carbondefi.xyz/litepaper
- Whitepaper: https://carbondefi.xyz/whitepaper
- Docs: https://docs.carbondefi.xyz
- AI Agents & MCP Integration: https://docs.carbondefi.xyz/ai-agents-and-mcp-integration

## Links

- Website: https://carbondefi.xyz
- App: https://app.carbondefi.xyz
- Docs: https://docs.carbondefi.xyz
- GitHub: https://github.com/bancorprotocol/ai

# Claude Skill
skill-file: https://mcp.carbondefi.xyz/carbon-defi.skill
skill-raw: https://mcp.carbondefi.xyz/SKILL.md