Carbon DeFi , On-Chain Maker Trading via MCP

Carbon DeFi is a fully on-chain maker trading protocol. you set prices upfront, strategies execute automatically with zero gas on fills. no bots, no agent needs to stay online after placing a strategy.

intent

use this skill when a user wants to create, view, manage, or close on-chain maker trading strategies on Carbon DeFi. this covers limit orders (buy/sell at exact price), range orders (scale in/out across a price band), recurring strategies (looping buy-sell pairs), and concentrated or full-range liquidity provision. you control execution by setting prices and budgets before transaction broadcast. carbon handles matching and fills with zero slippage against maker liquidity. this skill applies across ethereum, sei, celo, tac, and coti networks.

inputs

MCP Server Setup (pick one):

Option A: Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Restart Claude Desktop after adding.

Option B: REST API endpoint (no auth required):

https://mcp.carbondefi.xyz/tools/:toolName

Rate limit: 30 req/min per IP, burst of 10. use /batch for parallel calls (counts as 1 request).

User-Provided Data:

• wallet address (0x format)
• chain name: ethereum, sei, celo, tac, coti
• token symbols or addresses (base and quote tokens)
• market price (always ask, never reuse from earlier in conversation)
• desired buy/sell prices
• budget amounts (in quote token for buys, base token for sells)

External Connections:

• user's wallet signer (Metamask, WalletConnect, hardware wallet, etc.) to sign and broadcast transactions
• ERC-20 token allowance to Carbon DeFi controller (must be set before depositing non-ETH tokens)

Context:

• existing active strategies (fetch first with carbon_get_strategies)
• current market price for the pair (ask user, never assume)
• token decimals and addresses (resolve via carbon_resolve_token if ambiguous)
• USDT on ethereum requires allowance set to 0 before increasing

procedure

Step 1: Retrieve existing strategies

Input: wallet address, chain. Action: call carbon_get_strategies. Output: list of active strategies (IDs, types, statuses, prices, budgets, trade counts). Why: verify user doesn't already have conflicting positions; inform next steps.

Step 2: Resolve token addresses

Input: user's base and quote token symbols or names. Action: call carbon_resolve_token for each token if not already a 0x address. Output: canonical on-chain addresses, decimals. Why: avoid typos and symbol collisions (e.g. "dollar" resolves to USDC/USDT/DAI, need user to pick).

Step 3: Get current market price

Input: base token, quote token, chain. Action: ask user for current market price. do not invent or reuse old prices. optionally call carbon_get_price_history to show recent OHLC. Output: user-confirmed market price (quote per 1 base). Why: prices move; confirmed price is the foundation for buy/sell range logic.

Step 4: Propose strategy type and parameters

Input: user's intent ("buy at X", "scale in", "recurring", etc.), market price, budgets. Action: determine strategy type from intent table (see decision points). show user a summary: type, price range, budget, expected execution pattern. do not build a transaction yet. Output: strategy proposal (text, no on-chain data). Why: explicit approval before building unsigned transaction.

Step 5: Wait for explicit user approval

Input: strategy proposal. Action: user confirms or requests changes. Output: approval signal. Why: prevents accidental on-chain execution.

Step 6: Call appropriate creation tool

Input: approved strategy params (base, quote, buy_price, sell_price, buy_budget, sell_budget, chain, etc.). Action: call one of: carbon_create_limit_order, carbon_create_range_order, carbon_create_recurring_strategy, carbon_create_concentrated_strategy, carbon_create_full_range_strategy. Output: unsigned transaction object (to, data, value), warnings array. Why: transaction is not yet broadcast; user signs and broadcasts manually.

Step 7: Check and display warnings

Input: warnings array from creation response. Action: if allowance warning present, show approval steps (call carbon_approve_token, sign, broadcast, wait for confirmation). else if price warnings, show adjustments and confirm user still wants to proceed. Output: approval instructions or confirmation. Why: ERC-20 approvals and price mismatches must be resolved before main transaction.

Step 8: Display unsigned transaction

Input: unsigned transaction object. Action: show full tx details (to address, data hex, value). provide link to spec (https://docs.carbondefi.xyz/developer-guides/carbon-defi-transaction-encoding) for user to verify calldata independently if desired. Output: transaction ready to sign. Why: transparency; user verifies and signs in their wallet.

Step 9: User signs and broadcasts

Input: unsigned transaction. Action: user opens wallet app, signs, broadcasts to chain. Output: tx hash. Why: only user controls signing; no agent broadcasts on their behalf.

Step 10: Confirm on-chain

Input: tx hash. Action: ask user for tx hash confirmation. optionally poll chain for receipt and call carbon_get_strategy to confirm new strategy is live. Output: confirmed strategy ID, live status. Why: verify strategy is actually on-chain.

Step 11 (optional): Manage existing strategy

Input: strategy ID, new parameters (if reprice/edit/deposit/withdraw/pause/resume/delete). Action: for reprice, call carbon_reprice_strategy with all four price points. for edit, call carbon_edit_strategy with prices and budgets. for deposit/withdraw, call respective tools. for pause/resume, show current state first, confirm, then call. for delete, confirm irreversibility, then call. Output: unsigned management transaction. Why: same approval and signing flow as creation.

decision points

Decision 1: Strategy Type

• If user says "buy at exactly X" or "sell at exactly X", use carbon_create_limit_order (one-time fill at that price).
• Else if user says "scale in" or "DCA into" or "buy gradually as price drops", use carbon_create_range_order with sell_budget = 0 (buy-only range).
• Else if user says "scale out" or "sell gradually" or "sell into rallies", use carbon_create_range_order with buy_budget = 0 (sell-only range).
• Else if user says "recurring" or "grid" or "buy low sell high forever", use carbon_create_recurring_strategy (looping buy-sell pair).
• Else if user says "provide liquidity" or "earn fees" or "concentrated", use carbon_create_concentrated_strategy (two-sided with defined spread).
• Else if user says "full range" or "widest range" or "catch everything", use carbon_create_full_range_strategy (two-sided up to 1000x from market).

Decision 2: Buy Range and Market Price

• If market price is below buy_price_max (user's highest buy price), the range partially overlaps the market.
  • Ask user: "do you want to buy anywhere down to [buy_price_min] (includes below market), or only below [market_price]?"
  • If user says "full range": omit buy_price_marginal. carbon will execute buys across entire range.
  • If user says "below market only": set buy_price_marginal to current market price. carbon will only execute buy fills below market.

Decision 3: Overlapping Buy and Sell Ranges

• If buy_price_min or buy_price_max overlaps with sell_price_min or sell_price_max, warn user: "your buy and sell ranges overlap. this is allowed but unusual; you may get filled on both sides simultaneously. confirm you want this."
• If user confirms, proceed. else, ask user to adjust prices.

Decision 4: Price Sanity Checks

• If buy_price > current market price, warn: "your buy price is above market. do you want to adjust to [market_price] or keep the original?"
• If sell_price < current market price, warn: "your sell price is below market. do you want to adjust to [market_price] or keep the original?"
• User can confirm or ask for adjustment.

Decision 5: Pause Confirmation

• Before pausing, call carbon_get_strategy to fetch current prices.
• Show user: "current buy range [X-Y], sell range [A-B]. pausing will freeze these orders. confirm?"
• Only call carbon_pause_strategy after explicit approval.

Decision 6: Resume (No Budget Ask)

• When resuming, only restore price ranges. do not ask for new budgets.
• Funds are already in the strategy; resuming reactivates orders at saved prices.
• Call carbon_resume_strategy with strategy ID only.

Decision 7: Reprice (Single Call)

• when repricing, always call carbon_reprice_strategy once with all four price points (buy_price_min, buy_price_max, sell_price_min, sell_price_max).
• if user only wants to change the buy side, fetch current strategy with carbon_get_strategy, extract sell prices, and include them in the reprice call.
• do not split into multiple calls.

Decision 8: Delete Confirmation

• Before calling carbon_delete_strategy, confirm with user: "this is irreversible. all funds in this strategy will be returned to your wallet. confirm?"
• only proceed after explicit "yes".

Decision 9: Token Allowance

• Before building a strategy that deposits an ERC-20 token (not ETH), check warnings in the creation response.
• If allowance warning present, show user: "you must approve [token] to Carbon DeFi first. we'll generate an approval tx. sign and broadcast it, wait for confirmation, then come back to complete the strategy."
• Provide unsigned approval transaction.
• Only after user confirms approval tx is on-chain, proceed to build and sign the main strategy tx.
• Special case: USDT on ethereum requires allowance set to 0 first, then increased. document this step.

Decision 10: Trade vs Strategy

• If user wants to swap tokens against carbon liquidity (not create a maker order), use carbon_get_trade_quote then carbon_execute_trade.
• If user wants to create a maker order (place a limit, range, recurring, or liquidity provision), use the creation tools above.

Decision 11: Network Selection

• If user doesn't specify chain, ask which: ethereum, sei, celo, tac, coti.
• If ambiguous (e.g. "ethereum or sei"), ask user to pick one; strategies are per-chain.

Decision 12: Native ETH vs WETH

• always use native ETH address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.
• never suggest WETH.
• native ETH never requires approval.

output contract

all write operations return an unsigned transaction object with fields:

• to: recipient address (carbon controller on the chain).
• data: encoded function call (hex string, verify via spec).
• value: wei amount to send (0 for most ops, non-zero for native ETH deposits).

creation tools also return:

• strategy_id: (optional, if strategy is pre-assigned) identifier for the new strategy.
• warnings: array of warning objects (e.g. allowance, price, overlap). each warning has type and message.

management tools (reprice, edit, deposit, withdraw, pause, resume, delete) return the same unsigned tx structure.

success means:

• transaction object is syntactically valid (can be decoded via spec).
• warnings array is empty or user has confirmed action despite warnings.
• user has signed and broadcast the tx (you do not broadcast).
• user reports tx hash.
• (optional) you call carbon_get_strategy or carbon_get_activity to confirm on-chain result after block confirmation.

data format:

• all prices as decimal strings (e.g. "2000.5" for 2000.5 USDC per ETH). carbon converts to marginal price encoding internally.
• all budgets as decimal strings in token units (e.g. "1.5" for 1.5 ETH).
• all addresses as 0x-prefixed hex strings.
• all chain names lowercase (ethereum, sei, celo, tac, coti).

file location:

• unsigned transactions are displayed in chat and shown to user for copying into their wallet. do not save to disk unless user explicitly asks.
• you do not have write access to user's chain; only the user's signed transaction can modify state.

outcome signal

success is user-confirmed and on-chain:

1. for creation (limit, range, recurring, concentrated, full-range):

   • user sees unsigned transaction and confirms it looks correct.
   • user signs in wallet (metamask, ledger, etc.).
   • user reports tx hash.
   • (wait for block confirmation, typically 1-2 min on ethereum.)
   • you call carbon_get_strategies and confirm new strategy appears in list with correct type, prices, budgets, and status = active.
   • user can now monitor trades in carbon app (https://app.carbondefi.xyz).

2. for management (reprice, edit, deposit, withdraw, pause, resume, delete):

   • user sees unsigned tx, confirms, signs, reports hash.
   • you call carbon_get_strategy with strategy ID and confirm state has changed (prices updated, budget increased/decreased, status paused, or strategy deleted).
   • user sees updated strategy on app.

3. for token approval (if needed):

   • user signs approval tx and reports hash.
   • you wait for confirmation and confirm allowance via on-chain query (optional but reassuring).
   • proceed to main strategy tx.

4. for trade (swap against carbon liquidity):

   • user sees trade quote (input, output, rate, slippage).
   • user signs and broadcasts.
   • on-chain: user receives output tokens.

signals that indicate failure or non-completion:

• user reports "tx reverted" or "out of gas" (user must troubleshoot, you offer guidance via spec and docs).
• user never signs or broadcasts (strategy was never created on-chain; no harm done).
• user signs but broadcasts to wrong chain (irreversible; encourage them to use correct chain next time).
• strategy fails to appear in carbon_get_strategies after confirmation (highly unlikely but call carbon_get_activity for clues; may be indexer lag).