@andrewkimjoseph/celina-sdk 0.4.6 → 0.4.8

package/README.md

@@ -1,9 +1,21 @@
 # Celina SDK
 
-Celina-linked mainnet library for frontend apps: **reads** and **unsigned transaction preparation** (no private keys).
+**`@andrewkimjoseph/celina-sdk@0.4.7`** — Celo mainnet library for frontend apps and agents: **reads** and **unsigned transaction preparation** (no private keys).
 
 Pair with [wagmi](https://wagmi.sh) / viem — users sign prepared transactions in their wallet.
 
+## Stack
+
+Celina is layered from chain logic through agent tooling:
+
+| Layer | Package | Role |
+|-------|---------|------|
+| **SDK** | `@andrewkimjoseph/celina-sdk` | Reads, gas estimates, `prepare*` flows, Carbon REST + SDK hybrid |
+| **MCP** | `@andrewkimjoseph/celina-mcp` | MCP tools for Cursor / Claude / LM Studio — stdio writes or hosted reads + Carbon prepare |
+| **MCP host** | `celina-mcp-host` | Vercel Streamable HTTP — hosted reads + Carbon prepare (71 tools); no server-key writes or `execute_carbon_*` |
+
+This repo is the **SDK**. Downstream packages depend on published npm semver (no local `file:` links in production).
+
 ## Install
 
 ```bash
@@ -17,12 +29,13 @@ Requires Node.js ≥ 20.
 **Full docs:** [celina-sdk on GitBook](https://andrewkimjoseph.gitbook.io/celina-sdk)
 
 - [Quick start](https://andrewkimjoseph.gitbook.io/celina-sdk/getting-started/quick-start)
+- [Architecture](docs/concepts/architecture.md) — client composition and stack
+- [Prepared flows](docs/concepts/prepared-flows.md) — `SerializedPreparedFlow`, CELINA calldata tag
 - [wagmi integration](https://andrewkimjoseph.gitbook.io/celina-sdk/guides/wagmi-integration)
-- [Aave](https://andrewkimjoseph.gitbook.io/celina-sdk/guides/aave)
-- [GoodDollar UBI](docs/guides/gooddollar.md) — whitelist, daily entitlement, `prepareClaimUbi` on Celo
-- [Carbon DeFi on Celo](docs/guides/carbon.md) — hybrid Carbon REST + `@bancor/carbon-sdk` (25 operations)
-- [Self Agent ID](docs/guides/self-agent-id.md) — verify, register, and refresh human-backed agents on Celo
-- [Telemetry](docs/guides/telemetry.md) — optional Amplitude read metrics (opt out with `CELINA_ANALYTICS_DISABLED=1`)
+- [Carbon DeFi on Celo](docs/guides/carbon.md) — hybrid REST + `@bancor/carbon-sdk` (25 operations)
+- [GoodDollar UBI](docs/guides/gooddollar.md) — whitelist, daily entitlement, `prepareClaimUbi`
+- [Self Agent ID](docs/guides/self-agent-id.md) — verify, register, refresh human-backed agents
+- [Telemetry](docs/guides/telemetry.md) — optional Amplitude read metrics (`CELINA_ANALYTICS_DISABLED=1`)
 - [API reference](https://andrewkimjoseph.gitbook.io/celina-sdk/api-reference)
 
 Docs source lives in [`docs/`](docs/) in this repository.
@@ -37,7 +50,7 @@ const celina = createCelinaClient();
 await celina.token.getStablecoinBalances("0xYourAddress");
 
 const flow = await celina.transaction.prepareSend("0xFrom", "0xTo", "USDm", "10");
-// flow.steps → pass to wagmi sendTransaction
+// flow.steps → pass to wagmi sendTransaction (calldata includes CELINA attribution suffix)
 
 // Carbon DeFi (reads + unsigned strategy/trade prep)
 const strategies = await celina.carbon.getStrategies("0xYourAddress");
@@ -49,40 +62,57 @@ const prepared = await celina.carbon.prepareLimitOrder({
   price: 0.5,
   budget: 100,
 });
-// prepared.preparedFlow?.steps → same signing flow; check prepared.warnings
+// prepared.preparedFlow?.steps — controller + approve steps, all tagged
+// prepared.deep_link — Carbon trade UI reference (optional)
+// prepared.warnings — always surface to the user
 
 // GoodDollar UBI (reads + unsigned claim)
 const eligibility = await celina.gooddollar.getUbiClaimEligibility("0xYourAddress");
 const ubiFlow = await celina.gooddollar.prepareClaimUbi("0xYourAddress");
-// ubiFlow.steps → wagmi sendTransaction (G$ to signer, gas in CELO)
 ```
 
-## GoodDollar UBI
+## Prepared flows and calldata tagging
 
-Identity whitelist reads, daily entitlement checks, and unsigned `UBISchemeV2.claim()` preparation on Celo mainnet. One claim per verified identity per day; connected wallets resolve via `getWhitelistedRoot`.
+All `prepare*` methods return a **`SerializedPreparedFlow`**: ordered unsigned steps for the user's wallet.
 
-| Reads (`celina.gooddollar`) | Prepare (unsigned) |
-|-----------------------------|-------------------|
-| `getWhitelistingInfo`, `getUbiClaimEligibility` | `prepareClaimUbi` |
+Every step with calldata gets a **CELINA attribution suffix** (`appendCelinaCalldataTag`) — sends, Mento FX, Uniswap, Aave, GoodDollar, and **Carbon controller transactions** (not just ERC-20 approvals). Pass `step.data` to wagmi unchanged.
 
-MCP tools: `get_gooddollar_whitelisting_info`, `get_gooddollar_ubi_entitlement` (read); `claim_daily_gooddollar_ubi` (stdio write with server key). Full workflow: [GoodDollar guide](docs/guides/gooddollar.md).
+See [Prepared flows](docs/concepts/prepared-flows.md).
 
 ## Carbon DeFi
 
-Hybrid **Carbon REST** (`https://mcp.carbondefi.xyz`) plus **`@bancor/carbon-sdk`** fallback for trade quotes and taker swaps when REST is unavailable. All 25 operations target Celo mainnet; no private keys — `prepare*` returns unsigned flows for the user’s wallet.
+Hybrid **Carbon REST** (`https://mcp.carbondefi.xyz`) plus **`@bancor/carbon-sdk`** fallback for trade quotes and taker swaps when REST is unavailable. All 25 operations target Celo mainnet.
 
 | Reads (`celina.carbon`) | Prepare (unsigned) |
 |-------------------------|-------------------|
-| `getStrategies`, `getStrategy`, `getTradeQuote`, `explorePair`, `resolveToken`, `getActivity`, `findOpportunities`, `getProtocolStats`, `getPriceHistory`, `simulateStrategy`, `help`, `learn` | `prepareLimitOrder`, `prepareRangeOrder`, `prepareRecurringStrategy`, `prepareConcentratedStrategy`, `prepareFullRangeStrategy`, `prepareRepriceStrategy`, `prepareEditStrategy`, `prepareDepositBudget`, `prepareWithdrawBudget`, `preparePauseStrategy`, `prepareResumeStrategy`, `prepareDeleteStrategy`, `prepareTrade` |
+| `getStrategies`, `getStrategy`, `getTradeQuote`, `explorePair`, `resolveToken`, `getActivity`, `findOpportunities`, `getProtocolStats`, `getPriceHistory`, `simulateStrategy`, `help`, `learn` | 13 `prepare*` methods — limit/range/recurring/concentrated/full-range orders, edit/reprice/deposit/withdraw/pause/resume/delete, taker `prepareTrade` |
+
+- Token symbols are **normalized to `0x` addresses** before Carbon REST (avoids ENS resolution errors on Celo).
+- **`finalizeCarbonPrepare(carbon, wallet, prepared, orderMeta)`** — merges ERC-20 approve steps via `buildExecutionSteps` into `preparedFlow.steps` (used by MCP `prepare_carbon_*` and browser apps).
+- **`deep_link`** on prepare responses — Carbon REST trade/disposable UI URL (reference only; signing is via your wallet flow).
+- **`carbonActivityDeepLink(wallet)`** — post-execution activity explorer on [celo.carbondefi.xyz](https://celo.carbondefi.xyz).
+
+Set `CARBON_API_BASE_URL` to override the REST base. Hosted MCP exposes **12 read + 13 prepare** tools (71 total); `execute_carbon_*` requires local stdio with `CELO_PRIVATE_KEY`.
+
+Full workflow: [Carbon DeFi guide](docs/guides/carbon.md).
+
+## GoodDollar UBI
+
+Identity whitelist reads, daily entitlement checks, and unsigned `UBISchemeV2.claim()` preparation. One claim per verified identity per day.
+
+| Reads | Prepare |
+|-------|---------|
+| `getWhitelistingInfo`, `getUbiClaimEligibility` | `prepareClaimUbi` |
 
-Set `CARBON_API_BASE_URL` to override the REST base. Hosted [celina-mcp](https://mcp.usecelina.xyz/api/mcp) exposes the 12 read tools only; use this SDK or local MCP stdio for all `prepare*` methods.
+MCP: `get_gooddollar_whitelisting_info`, `get_gooddollar_ubi_entitlement` (read); `claim_daily_gooddollar_ubi` (stdio write with server key). Browser apps: `prepareClaimUbi` + wagmi.
 
-Full workflow, MCP tool names, and env vars: [Carbon DeFi guide](docs/guides/carbon.md).
+[GoodDollar guide](docs/guides/gooddollar.md)
 
 ## Related packages
 
-- [`@andrewkimjoseph/celina-mcp`](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) — MCP server for IDE/CLI agents
-- [`@selfxyz/agent-sdk`](https://www.npmjs.com/package/@selfxyz/agent-sdk) — Self Agent ID
+- [`@andrewkimjoseph/celina-mcp`](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) `@0.8.4` — MCP server (38 Carbon tools on stdio; hosted: 12 read + 13 prepare)
+- [`celina-mcp-host`](../celina-mcp-host/) — Vercel-hosted MCP endpoint (`https://mcp.usecelina.xyz/api/mcp`) — reads + Carbon prepare
+- [`@selfxyz/agent-sdk`](https://www.npmjs.com/package/@selfxyz/agent-sdk) — Self Agent ID browser flows
 
 ## License
 

package/build/analytics/mcp-tool-events.js

@@ -4,6 +4,7 @@
  */
 export const MCP_TOOL_EVENT_BY_SDK_METHOD = {
     "account.getAccount": "get_account",
+    "account.getWalletAddress": "get_wallet_address",
     "blockchain.getBlock": "get_block",
     "blockchain.getLatestBlocks": "get_latest_blocks",
     "blockchain.getNetworkStatus": "get_network_status",

package/build/analytics/mcp-tool-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-tool-events.js","sourceRoot":"","sources":["../../src/analytics/mcp-tool-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAqC;IAC5E,oBAAoB,EAAE,aAAa;IACnC,qBAAqB,EAAE,WAAW;IAClC,4BAA4B,EAAE,mBAAmB;IACjD,6BAA6B,EAAE,oBAAoB;IACnD,2BAA2B,EAAE,iBAAiB;IAC9C,oBAAoB,EAAE,qBAAqB;IAC3C,0BAA0B,EAAE,2BAA2B;IACvD,oBAAoB,EAAE,qBAAqB;IAC3C,wBAAwB,EAAE,0BAA0B;IACpD,yBAAyB,EAAE,2BAA2B;IACtD,sBAAsB,EAAE,uBAAuB;IAC/C,oBAAoB,EAAE,qBAAqB;IAC3C,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,aAAa;IAC5B,cAAc,EAAE,cAAc;IAC9B,qBAAqB,EAAE,sBAAsB;IAC7C,yBAAyB,EAAE,0BAA0B;IACrD,uBAAuB,EAAE,wBAAwB;IACjD,sBAAsB,EAAE,uBAAuB;IAC/C,gBAAgB,EAAE,aAAa;IAC/B,mCAAmC,EAAE,gCAAgC;IACrE,gCAAgC,EAAE,kCAAkC;IACpE,mCAAmC,EAAE,0BAA0B;IAC/D,+BAA+B,EAAE,sBAAsB;IACvD,oBAAoB,EAAE,mBAAmB;IACzC,oBAAoB,EAAE,oBAAoB;IAC1C,mBAAmB,EAAE,iBAAiB;IACtC,gBAAgB,EAAE,cAAc;IAChC,6BAA6B,EAAE,0BAA0B;IACzD,4BAA4B,EAAE,yBAAyB;IACvD,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,wBAAwB,EAAE,qBAAqB;IAC/C,8BAA8B,EAAE,wBAAwB;IACxD,4BAA4B,EAAE,sBAAsB;IACpD,6BAA6B,EAAE,wBAAwB;IACvD,kCAAkC,EAAE,6BAA6B;IACjE,4BAA4B,EAAE,sBAAsB;IACpD,mBAAmB,EAAE,mBAAmB;IACxC,6BAA6B,EAAE,yBAAyB;IACxD,uBAAuB,EAAE,mBAAmB;IAC5C,oBAAoB,EAAE,gBAAgB;IACtC,0BAA0B,EAAE,eAAe;IAC3C,iCAAiC,EAAE,sBAAsB;IACzD,2BAA2B,EAAE,kBAAkB;IAC/C,sBAAsB,EAAE,uBAAuB;IAC/C,sBAAsB,EAAE,mBAAmB;CACnC,CAAC"}
+{"version":3,"file":"mcp-tool-events.js","sourceRoot":"","sources":["../../src/analytics/mcp-tool-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAqC;IAC5E,oBAAoB,EAAE,aAAa;IACnC,0BAA0B,EAAE,oBAAoB;IAChD,qBAAqB,EAAE,WAAW;IAClC,4BAA4B,EAAE,mBAAmB;IACjD,6BAA6B,EAAE,oBAAoB;IACnD,2BAA2B,EAAE,iBAAiB;IAC9C,oBAAoB,EAAE,qBAAqB;IAC3C,0BAA0B,EAAE,2BAA2B;IACvD,oBAAoB,EAAE,qBAAqB;IAC3C,wBAAwB,EAAE,0BAA0B;IACpD,yBAAyB,EAAE,2BAA2B;IACtD,sBAAsB,EAAE,uBAAuB;IAC/C,oBAAoB,EAAE,qBAAqB;IAC3C,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,aAAa;IAC5B,cAAc,EAAE,cAAc;IAC9B,qBAAqB,EAAE,sBAAsB;IAC7C,yBAAyB,EAAE,0BAA0B;IACrD,uBAAuB,EAAE,wBAAwB;IACjD,sBAAsB,EAAE,uBAAuB;IAC/C,gBAAgB,EAAE,aAAa;IAC/B,mCAAmC,EAAE,gCAAgC;IACrE,gCAAgC,EAAE,kCAAkC;IACpE,mCAAmC,EAAE,0BAA0B;IAC/D,+BAA+B,EAAE,sBAAsB;IACvD,oBAAoB,EAAE,mBAAmB;IACzC,oBAAoB,EAAE,oBAAoB;IAC1C,mBAAmB,EAAE,iBAAiB;IACtC,gBAAgB,EAAE,cAAc;IAChC,6BAA6B,EAAE,0BAA0B;IACzD,4BAA4B,EAAE,yBAAyB;IACvD,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,sBAAsB,EAAE,mBAAmB;IAC3C,wBAAwB,EAAE,qBAAqB;IAC/C,8BAA8B,EAAE,wBAAwB;IACxD,4BAA4B,EAAE,sBAAsB;IACpD,6BAA6B,EAAE,wBAAwB;IACvD,kCAAkC,EAAE,6BAA6B;IACjE,4BAA4B,EAAE,sBAAsB;IACpD,mBAAmB,EAAE,mBAAmB;IACxC,6BAA6B,EAAE,yBAAyB;IACxD,uBAAuB,EAAE,mBAAmB;IAC5C,oBAAoB,EAAE,gBAAgB;IACtC,0BAA0B,EAAE,eAAe;IAC3C,iCAAiC,EAAE,sBAAsB;IACzD,2BAA2B,EAAE,kBAAkB;IAC/C,sBAAsB,EAAE,uBAAuB;IAC/C,sBAAsB,EAAE,mBAAmB;CACnC,CAAC"}

package/build/index.d.ts

@@ -87,6 +87,7 @@ export type { CarbonWriteBody } from "./services/carbon.service.js";
 export { CARBON_APP_BASE_URL, CARBON_CHAIN, CELO_CARBON_CONTRACTS, DEFAULT_CARBON_REST_BASE_URL, carbonActivityDeepLink, } from "./config/carbon.js";
 export { resolveCarbonTokenAddress, normalizeCarbonWriteBody, CARBON_WRITE_TOKEN_FIELDS, } from "./utils/carbon-token.js";
 export { buildCarbonExecutionSteps } from "./utils/carbon-execution.js";
+export { finalizeCarbonPrepare, type FinalizedCarbonPrepareFlow, } from "./utils/finalize-carbon-prepare.js";
 export { CarbonRestError } from "./clients/carbon-rest.js";
 export { SelfService, type VerifySelfAgentParams, type VerifySelfRequestParams, type RegisterSelfAgentParams, } from "./services/self.service.js";
 export { SelfApiError, SelfExpiredSessionError, } from "./clients/self-api.js";

package/build/index.js

@@ -60,6 +60,7 @@ export { GOODDOLLAR_IDENTITY_ADDRESS, GOODDOLLAR_UBI_SCHEME_ADDRESS, } from "./c
 export { CARBON_APP_BASE_URL, CARBON_CHAIN, CELO_CARBON_CONTRACTS, DEFAULT_CARBON_REST_BASE_URL, carbonActivityDeepLink, } from "./config/carbon.js";
 export { resolveCarbonTokenAddress, normalizeCarbonWriteBody, CARBON_WRITE_TOKEN_FIELDS, } from "./utils/carbon-token.js";
 export { buildCarbonExecutionSteps } from "./utils/carbon-execution.js";
+export { finalizeCarbonPrepare, } from "./utils/finalize-carbon-prepare.js";
 export { CarbonRestError } from "./clients/carbon-rest.js";
 export { SelfService, } from "./services/self.service.js";
 export { SelfApiError, SelfExpiredSessionError, } from "./clients/self-api.js";

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/utils/finalize-carbon-prepare.d.ts

@@ -0,0 +1,10 @@
+import type { CarbonService } from "../services/carbon.service.js";
+import type { CarbonPrepareResult } from "../types/carbon.js";
+import type { SerializedPreparedFlow } from "../types/prepared.js";
+export type FinalizedCarbonPrepareFlow = SerializedPreparedFlow & {
+    deep_link?: string;
+    warnings?: string[];
+    strategyPreview?: unknown;
+};
+/** Merge Carbon REST prepare + ERC-20 approve steps for external wallet signing. */
+export declare function finalizeCarbonPrepare(carbon: Pick<CarbonService, "buildExecutionSteps">, from: `0x${string}`, prepared: CarbonPrepareResult, orderMeta: Record<string, unknown>): Promise<FinalizedCarbonPrepareFlow>;

package/build/utils/finalize-carbon-prepare.js

@@ -0,0 +1,17 @@
+/** Merge Carbon REST prepare + ERC-20 approve steps for external wallet signing. */
+export async function finalizeCarbonPrepare(carbon, from, prepared, orderMeta) {
+    const steps = await carbon.buildExecutionSteps(from, prepared, orderMeta);
+    if (!prepared.preparedFlow) {
+        throw new Error("Carbon prepare returned no transaction steps.");
+    }
+    return {
+        ...prepared.preparedFlow,
+        steps,
+        ...(prepared.deep_link ? { deep_link: String(prepared.deep_link) } : {}),
+        ...(prepared.warnings?.length ? { warnings: prepared.warnings } : {}),
+        ...(prepared.strategyPreview !== undefined
+            ? { strategyPreview: prepared.strategyPreview }
+            : {}),
+    };
+}
+//# sourceMappingURL=finalize-carbon-prepare.js.map

package/build/utils/finalize-carbon-prepare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize-carbon-prepare.js","sourceRoot":"","sources":["../../src/utils/finalize-carbon-prepare.ts"],"names":[],"mappings":"AAUA,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAkD,EAClD,IAAmB,EACnB,QAA6B,EAC7B,SAAkC;IAElC,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC1E,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IAED,OAAO;QACL,GAAG,QAAQ,CAAC,YAAY;QACxB,KAAK;QACL,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS;YACxC,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE;YAC/C,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrewkimjoseph/celina-sdk",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Celina SDK — Celo mainnet reads and unsigned transaction preparation for frontend apps.",
   "type": "module",
   "sideEffects": false,

package/tests/catalog/domains/blockchain.ts

@@ -88,4 +88,22 @@ export const blockchainOperations: OperationSpec[] = [
       assertHasKeys(result, ["address", "balanceWei"]);
     },
   },
+  {
+    id: "account.getWalletAddress",
+    domain: "blockchain",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    mcp: {
+      tool: "get_wallet_address",
+      arguments: () => ({}),
+    },
+    assert: (result, fx) => {
+      const obj = assertHasKeys(result, ["wallet_address", "has_wallet", "source"]);
+      expect(obj.has_wallet).toBe(true);
+      expect(String(obj.wallet_address).toLowerCase()).toBe(
+        fx.wallet.toLowerCase(),
+      );
+      expect(obj.source).toBe("CELO_PRIVATE_KEY");
+    },
+  },
 ];

package/tests/catalog/domains/carbon.ts

@@ -40,6 +40,23 @@ function carbonPrepare(
   };
 }
 
+function carbonExecute(
+  id: string,
+  tool: string,
+  args: () => Record<string, unknown>,
+): OperationSpec {
+  return {
+    id,
+    domain: "carbon",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: { tool, arguments: args },
+    assert: (result) => assertHasKeys(result, ["hash", "from"]),
+    skip: () => "Set CELINA_TEST_WRITES=1 to run on-chain Carbon execute tests",
+  };
+}
+
 export const carbonOperations: OperationSpec[] = [
   carbonRead(
     "carbon.getStrategies",
@@ -406,4 +423,125 @@ export const carbonOperations: OperationSpec[] = [
       min_return: "0",
     }),
   ),
+  carbonExecute(
+    "carbon.executeLimitOrder",
+    "execute_carbon_limit_order",
+    () => ({
+      base_token: CELO,
+      quote_token: USDC,
+      direction: "buy",
+      price: 0.5,
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeRangeOrder",
+    "execute_carbon_range_order",
+    () => ({
+      base_token: CELO,
+      quote_token: USDC,
+      direction: "buy",
+      price: 0.5,
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeRecurringStrategy",
+    "execute_carbon_recurring_strategy",
+    () => ({
+      base_token: CELO,
+      quote_token: USDC,
+      direction: "buy",
+      price: 0.5,
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeConcentratedStrategy",
+    "execute_carbon_concentrated_strategy",
+    () => ({
+      base_token: CELO,
+      quote_token: USDC,
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeFullRangeStrategy",
+    "execute_carbon_full_range_strategy",
+    () => ({
+      base_token: CELO,
+      quote_token: USDC,
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeRepriceStrategy",
+    "execute_carbon_reprice_strategy",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+      price: 0.5,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeEditStrategy",
+    "execute_carbon_edit_strategy",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+      price: 0.5,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeDepositBudget",
+    "execute_carbon_deposit_budget",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeWithdrawBudget",
+    "execute_carbon_withdraw_budget",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+      budget: 1,
+    }),
+  ),
+  carbonExecute(
+    "carbon.executePauseStrategy",
+    "execute_carbon_pause_strategy",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeResumeStrategy",
+    "execute_carbon_resume_strategy",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeDeleteStrategy",
+    "execute_carbon_delete_strategy",
+    () => ({
+      wallet_address: CARBON_WALLET,
+      strategy_id: "1",
+    }),
+  ),
+  carbonExecute(
+    "carbon.executeTrade",
+    "execute_carbon_trade",
+    () => ({
+      source_token: CELO,
+      target_token: USDC,
+      amount: "1",
+      min_return: "0",
+    }),
+  ),
 ];