bug: EURC → USDC has no swap route on Arc Testnet (error 331001) — only USDC → EURC direction works

[osr21]

Summary

When building a stablecoin swap dApp using Circle AppKit v1.5.0 on Arc Testnet (Chain ID 5042002), kit.estimateSwap() and kit.swap() always return a fatal routing error for the EURC → USDC direction.

Error

KitError: Stablecoin Service createSwap failed: Route or resource not found. Details: No route available
  name: INPUT_UNSUPPORTED_ROUTE (code 1003)
  recoverability: FATAL
  cause.trace.responseBody: { code: 331001, message: "No route available" }

Affected Directions

Direction	Result
USDC → EURC	✅ Works (intermittently — also returns 331001 when testnet routing is temporarily down)
EURC → USDC	❌ Always fails with code 331001

Reproduction

// Always fails with 331001:
await kit.estimateSwap({ fromToken: "EURC", toToken: "USDC", amount: "5" });

// Works most of the time:
await kit.estimateSwap({ fromToken: "USDC", toToken: "EURC", amount: "5" });

Root Cause

estimateSwap() internally calls Circle’s createSwap API, which routes through the lifi/Fly DEX integration. There appears to be no liquidity path seeded for EURC → USDC on Arc Testnet’s routing layer.

Impact

Any dApp offering bidirectional stablecoin swaps on Arc Testnet is broken for the EURC → USDC direction. Users who hold EURC cannot swap back to USDC, which creates a one-way liquidity trap in testnet UIs.

Suggested Fix / Documentation

Either:

1. Seed routing liquidity for EURC → USDC on the Arc Testnet lifi/Fly DEX layer
2. Or document which swap directions are currently supported on testnet so developers can disable unsupported directions in their UIs and avoid confusing users

For now, a safe workaround is to catch error code 1003 / Circle response code 331001 and surface a clear message:

try {
  await kit.estimateSwap(...);
} catch (err) {
  if (err.code === 1003 || err.cause?.trace?.responseBody?.code === 331001) {
    // No route — disable this swap direction in UI
  }
}

Environment

• Circle AppKit v1.5.0
• Arc Testnet Chain ID: 5042002
• RPC: https://rpc.testnet.arc.network
• USDC: 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 (6 decimals)
• EURC: 0x89B5... (6 decimals)

[osr21]

Confirming: USDC → EURC also fails intermittently; full Circle Kit swap unusable on Arc Testnet

Building Arc Swap on Arc Testnet, we hit the same 331001 error and can confirm the following:

Observed behavior

Direction	kit.estimateSwap()	kit.swap()
USDC → EURC	Returns result but rate is wrong (~17 EURC per USDC instead of ~0.91)	Fails: ONCHAIN_SIMULATION_FAILED
EURC → USDC	Fails: INPUT_UNSUPPORTED_ROUTE (code 331001)	Fails: ONCHAIN_SIMULATION_FAILED

So the routing failure reported here (EURC → USDC, 331001) is actually the less severe symptom — even the "working" USDC → EURC direction fails at execution time with ONCHAIN_SIMULATION_FAILED because the on-chain swap router has no liquidity on Arc Testnet.

What estimateSwap() returns for USDC → EURC

{
  "toAmount": "17.234521",
  "exchangeRate": "17.234521",
  "fee": "0.003"
}

This is approximately 19x the correct market rate (real EUR/USD ≈ 0.91 at time of testing). The testnet routing pool appears to use artificial/stale liquidity for the estimate.

Workaround

We replaced Circle Kit entirely with real market rates from the Frankfurter ECB forex API and settled swaps via direct ERC-20 peer-to-peer transfers. See the workaround write-up in circlefin/arc-node#88 for full details.

Environment

• @circle-fin/app-kit v1.5.x
• Arc Testnet, Chain ID 5042002

[osr21]

Root cause found: missing User-Agent header + missing toAddress parameter

Building ArcLend — an Aave-style lending/borrowing dApp on Arc Testnet — we integrated Circle's Stablecoin Kits using the raw HTTP API rather than the @circle-fin/app-kit SDK, and found two undocumented requirements that explain the intermittent 331001 failures even on the USDC → EURC direction:

---

Root cause 1 — missing User-Agent header

Circle's routing service gates Arc Testnet routes on SDK identification. Without the header, both USDC → EURC and EURC → USDC return { code: 331001, message: "No route available" } every time, not just intermittently.

Required header on every request:

User-Agent: swap-kit/1.0 (node/24)

This is visible in @circle-fin/swap-kit's bundled source (index.cjs) as the default header set before each API call. When you call the API directly (e.g. from a server proxy), this header is not added automatically by the HTTP client.

Root cause 2 — toAddress is required on the quote endpoint

The quote endpoint (/v1/stablecoinKits/quote) requires both fromAddress and toAddress as query parameters. Omitting toAddress returns a routing error that looks identical to 331001. It is not listed as required in the public docs.

---

Working solution — server-side proxy

We keep the CIRCLE_KIT_KEY server-side and proxy all requests through Express:

// GET /api/swap/quote
const url = new URL("https://api.circle.com/v1/stablecoinKits/quote");
url.searchParams.set("fromToken", req.query.fromToken);
url.searchParams.set("toToken",   req.query.toToken);
url.searchParams.set("amount",    req.query.amount);
url.searchParams.set("fromAddress", req.query.fromAddress);
url.searchParams.set("toAddress",   req.query.toAddress);  // ← required

const res = await fetch(url.toString(), {
  headers: {
    "Authorization": `Bearer ${process.env.CIRCLE_KIT_KEY}`,
    "User-Agent":    "swap-kit/1.0 (node/24)",              // ← required
  },
});

On-chain execution uses PermitType.NONE (pre-approval): USDC on Arc is an ERC-20 precompile and does not implement EIP-2612, so permit-based flows fail silently.

// after approve(adapterContract, amount):
await adapterContract.execute(executionParams, tokenInputs, circleSignature);

Confirmed working swap transaction (USDC → EURC on Arc Testnet):
0x5f6ac0da044878b2461bfb6fa3ff8ff523dabfddd9c746a11f98c0b57a1633f2

---

Summary

Direction	Status	Notes
USDC → EURC	✅ Works reliably	Requires User-Agent + toAddress + PermitType.NONE
EURC → USDC	❌ Still fails (331001)	Separate issue — no liquidity path on Arc's LiFi/Fly DEX layer regardless of headers

The ONCHAIN_SIMULATION_FAILED that AppKit returns on USDC → EURC execution (as reported in the comment above) was the SDK hitting a 331001 because it wasn't sending the right User-Agent. With the proxy approach this doesn't happen.

Full source: artifacts/api-server/src/routes/swap.ts in the ArcLend repo.

[osr21]

Confirmed 331001 — sharing an on-chain FX Forward contract as a bidirectional workaround

We hit the same EURC → USDC routing failure. Since Circle's SDK swap doesn't support this direction on Arc Testnet, we built a direct on-chain FX Forward contract as an alternative for developers who need bidirectional USDC ↔ EURC exchange.

FXForward contract

FXForward: 0x8029d9bDCdB9434468d1351CAB97f4FbBf028f80 (Arc Testnet, Chain ID 5042002)

Flow:

1. Party A calls createForward(partyB, usdcAmount, eurcAmount, maturity, fundingDeadline) — deposits USDC, sets implied FX rate
2. Party B calls fund(id) — deposits EURC before deadline
3. At maturity: settle(id) — A receives EURC, B receives USDC (either direction works)
4. If B never funds: A calls cancel(id) to reclaim USDC

// FXForward.sol — deployed at 0x8029d9bDCdB9434468d1351CAB97f4FbBf028f80
address public constant USDC = 0x3600000000000000000000000000000000000000;
address public constant EURC = 0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a;

// createForward: A deposits USDC, B must deposit EURC
// fund: B deposits EURC
// settle: A gets EURC, B gets USDC
// cancel: A reclaims USDC if B missed the funding deadline

Full source: FXForward.sol

Why it sidesteps the routing error

The contract interacts directly with Arc's USDC and EURC ERC-20 contracts via transferFrom — no routing layer, no Circle API, no liquidity path dependency. The FX rate is simply the ratio usdcAmount / eurcAmount agreed at creation time.

Limitations

This is OTC-style (both counterparties known), so it doesn't replace instant AMM-style swaps. But for:

• Treasury rebalancing where both sides are controlled
• B2B stablecoin settlement
• Testnet development where you hold both USDC and EURC from the faucet

…it works reliably today without ever touching the SDK routing layer that returns 331001.

Upvoting the original fix request — having the SDK routing work bidirectionally is the clean solution. Sharing this as a stop-gap for anyone blocked right now.

[osr21]

Hit this too — the Circle AppKit Swap SDK only supports USDC → EURC direction on Arc Testnet currently (error 331001 for the reverse).

Our workaround for the StableFX rate display in our DApp: instead of routing through AppKit swap for price discovery, we fetch the live EURC/USD rate from CoinGecko (/simple/price?ids=euro-coin&vs_currencies=usd, 60 s server-side cache, fallback rate 1.082) and use that as the reference rate for on-chain FX forward contract creation. This sidesteps the swap-route gap entirely for read-only rate display.

// GET /api/fx-rate — Express route (server-side, 60s cache)
const res = await fetch(
  "https://api.coingecko.com/api/v3/simple/price?ids=euro-coin&vs_currencies=usd"
);
const data = await res.json();
const rate = data["euro-coin"]?.usd ?? 1.082; // fallback if CoinGecko unreachable

For actual on-chain EURC→USDC swaps we haven't found a working path on Arc Testnet yet either. Is there a timeline for when this direction will be supported by the AppKit SDK?