/recover-eco-funds

name: recover-eco-funds
description: "Recover USDC from a legacy Circle CLI Gateway `--method eco` deposit whose fixed refund recipient is the SCA's backing EOA. Use this skill for legacy Eco intents that are stuck, expired, waiting for refund, refunded to `eoaOwnerAddress`, missing from Gateway, or need a permissionless self-refund. Do not use its executable recovery phases for current Gateway v2 deposits, which set `refundRecipient` to the SCA. It covers calling Eco's Portal `refund(...)` with exact onchain intent data, then moving refunded USDC from the backing EOA to the linked SCA with ERC-3009, relayed by the SCA so the backing EOA needs no gas. The backing-EOA sweep also applies when USDC was sent directly to an Agent Wallet's backing EOA and the CLI reports \"Wallet not found\" for that address."
allowed-tools: ["Read", "Bash(mkdir -p ./eco-recovery-evidence)", "Bash(circle --version)", "Bash(circle wallet status --output json)", "Bash(circle gateway deposit --help)", "Bash(circle wallet execute --help)", "Bash(circle contract query --help)", "Bash(circle wallet list --chain * --type agent --output json)", "Bash(circle wallet balance --address * --chain * --output json)", "Bash(circle gateway balance --address * --chain * --output json)", "Bash(circle transaction list --address * --chain * --operation transfer --tx-type outbound --state confirmed --output json)", "Bash(curl -fsS \"https://api.eco.com/circle-gateway/v2/depositAddresses/*\")", "Bash(curl -fsS --request POST --url https://quotes.eco.com/api/v3/intents/intentStatus --header \"Content-Type: application/json\" --data '{\"intentHash\":\"*\"}')", "Bash(curl -fsS --request POST --url https://quotes.eco.com/api/v3/intents/intentStatus --header \"Content-Type: application/json\" --data '{\"intentCreatedHash\":\"*\"}')", "Bash(*/node_modules/.bin/tsx */scripts/eco-self-refund.mjs *)", "Bash(node */scripts/sign-eoa-authorization.mjs *)"]
requirements:
  runtimes: [node]
  connectors: []

Recover Legacy Eco Funds

Overview

Recover funds from a legacy Circle CLI Eco deposit without guessing intent data, refund recipients, or transaction state. The workflow is evidence-first and defaults to read-only inspection.

> **Legacy-only recovery:** The executable recovery phases in this skill are for deposits whose already-published intent fixes `reward.creator` to the Circle SCA's API-verified `eoaOwnerAddress`. Current Gateway v2/Circle CLI deposits set `refundRecipient` to the SCA and should refund directly there. For a current deposit, use the read-only status checks below, reconcile the SCA and Gateway balances, and escalate through the normal support path if necessary; do not run the legacy backing-EOA sweep.

Do not classify a deposit as legacy from its age or endpoint version alone. Decode the `IntentPublished` event and compare the fixed `reward.creator` with both the SCA and its API-verified `eoaOwnerAddress`:

• `reward.creator == eoaOwnerAddress`: legacy recovery may apply after all read-only checks.
• `reward.creator == SCA`: current direct-to-SCA refund behavior; stop before the executable legacy phases.
• neither: stop because the selected Circle wallet does not own the fixed refund recipient.

If there is no Eco deposit and USDC was simply sent to an Agent Wallet's backing EOA (the CLI reports "Wallet not found" for that address), skip Phases 1 and 2 and go straight to [Phase 3](#phase-3-move-backing-eoa-usdc-to-the-linked-sca).

Use the `use-circle-cli` and `use-agent-wallet` skills first if the Circle CLI is not installed, the Terms gate is unresolved, or the agent session is invalid. Do not trigger multiple login requests: each fresh request invalidates the prior OTP.

Understand the two recovery legs

A legacy Eco deposit can require two separate operations:

1. **Eco self-refund:** call `Portal.refund(destination, routeHash, reward)` on the vault/refund chain after the reward deadline. The Portal validates the intent and instructs its deterministic vault to return funds to `reward.creator`. Anyone may relay this call, but the recipient is fixed by the original intent. 2. **Backing EOA sweep:** if `reward.creator` was the SCA's backing EOA, authorize USDC to move from that EOA to the linked SCA with ERC-3009. The SCA relays the token call and pays gas; the backing EOA does not need native gas.

Current Gateway v2/Circle CLI Eco deposits set the SCA as the refund recipient. They are outside the executable scope of this skill: use status and balance reconciliation, and do not run the backing-EOA sweep.

Safety boundary

• Treat event/creation chain, vault/refund chain, intent destination value, Gateway destination chain, SCA, backing EOA, creation-chain Portal, refund-chain Portal, vault, token, amount, route hash, intent hash, and deadline as different fields. Never substitute one for another. A composed Eco flow can publish the event on one chain while leaving the refundable vault on another, and Portal deployment addresses need not match across chains.
• Derive the backing EOA from the Circle wallet API's `eoaOwnerAddress`; do not accept a user-supplied owner without comparing it to that field.
• Before a legacy self-refund broadcast, require `reward.creator` to equal the selected Circle wallet's API-verified `eoaOwnerAddress`. If it equals the SCA, classify it as the current direct-to-SCA flow and stop before executable recovery. Although `refund(...)` is permissionless, never spend the user's gas to refund an unrelated wallet.
• Reconstruct the refund tuple from the source-chain `IntentPublished` event. The Eco status API is useful context but is not authoritative enough to build calldata.
• Verify the reconstructed intent hash equals the event's indexed intent hash.
• Refuse a refund before the onchain deadline or when reward status is already `Withdrawn` or `Refunded`.
• Simulate the exact calldata from the exact SCA before broadcasting.
• Ask for explicit approval immediately before each mon