WAGMI

We're All Gonna Make It

WAGMI FOR DEVELOPERS

Build on WAGMI.

Bring wallet data, swaps, transfers and Earn into your applications. Build trading tools, portfolio dashboards and automations with the WAGMI HTTP API.

Use the API for direct integration from your own code. Use MCP to connect AI assistants and agents to WAGMI tools. Both use the same underlying account permissions; the available actions depend on the interface.

Create API key →Connect an AI assistant →OpenAPI specification ↗

01 / CONNECT

Start in Settings

Sign in to your WAGMI account, open Settings → API & bots, name your integration, choose its wallet and permissions, choose 30 days, 90 days or Never expires, then create a key. You can revoke any key in Settings. Copy it once into your application’s server-side secret storage. Keep API keys out of browser and mobile client bundles.

API BASE URLhttps://wagmi-api.vercel.app/v1

The Settings labels “API & bots” and “Bot trading access” also apply to application integrations.

Use Authorization: Bearer $WAGMI_API_KEY. Read /me to get your wallet IDs. Read keys cannot sign transactions.

curl "$WAGMI_API_BASE/me" \
  -H "Authorization: Bearer $WAGMI_API_KEY"

curl "$WAGMI_API_BASE/arbs/active?wallet_id=$WALLET_ID&executable_only=false" \
  -H "Authorization: Bearer $WAGMI_API_KEY"

Requests are limited to 60 per minute per registration. Respect Retry-After and use exponential backoff.

02 / AUTHORIZE ONCE

Choose how your integration can execute

In Settings → Bot trading access, select your API key and wallet, enable swaps, Earn actions or transfers, choose networks and limits, and enter the wallet password once. Transfer recipients are a separate password-confirmed allowlist on that page. Add each intended recipient there before your integration can send to it. The same API key can then execute without pairing codes or approval for each trade.

Standing access lasts until revoked or until the key expires. Select Never expires when creating the key for ongoing access. Existing keys remain read-only until you enable execution. Your integration never receives the wallet password or signing shares.

Read /me for effective permissions and /bot/grants/current?wallet_id=… for the policy and remaining budgets. One wallet can have one active execution grant. Manual and API transactions take turns; wait for a pending operation to finish before starting another. Revocation stops new signing and cannot undo an already submitted transaction.

Standing access has no grant end time. Your application can keep calling the API until you revoke the grant or the key expires. The 60-minute cap is only a device-code access token, or the whole device-code grant when grant_duration_days is omitted. Your application may send grant_duration_days as 30 or 180. The owner picks 30, 180, or the short session when approving. A long session returns a rotating refresh token. POST /bot/authorizations/refresh issues a new access token until the grant expires, with no new approval. One wallet has one active grant, so unattended execution and a 30- or 180-day session are alternatives: revoke one before approving the other. Revoke the key under API & bots, or the grant under Bot trading access, and the grant and its refresh token stop immediately. Trade size, daily volume, daily loss and slippage stay on the approved policy. A 180-day session also needs an API key that is still valid for those 180 days. Choose Never expires when creating that key. Clients using standing access do not call the device-code or refresh endpoints.

Long-session clients must persist their session credentials and a UUID Idempotency-Key before each refresh. Retry an uncertain refresh with the same key and refresh token; use a new key for the next rotation. The last response is stored encrypted until the next rotation, and revocation or grant expiry disables retries. Keep session state private and durable so restarts can resume the session.

03 / EXECUTE

Quote. Accept. Follow settlement.

Use /swaps/quote for general trading, /transfers/quote for an allowlisted token transfer, /earn/deposit/quote or /earn/withdraw/quote for Earn, or an arbitrage quote for a listed opportunity. Discovery prices are indicative. A fresh quote includes minimum output, gas budget, expiry, venue and a conservative profit calculation.

Accept it with quote_id, wallet_id, a unique client_order_id and an Idempotency-Key. Save the request before sending. A timeout means retry the identical request and key, or query the saved execution.

QueuedSigningSubmittedSettlingFilled or refunded

Only filled means the swap settled. WAGMI verifies canonical receipts at Base’s safe threshold for same-chain swaps and Earn actions. Safe means published to Ethereum, before Ethereum finality. Cross-chain sequences and other networks require finalized receipts; bridges also require verified destination delivery or source refunds. Read settlement_progress.required_finality to see the threshold for your transaction. A confirmed bridge deposit remains pending until settlement is verified. Token approvals confirm after two blocks on the latest head once the receipt succeeds; they do not wait for safe or finalized, and they do not count as trading volume. If the refreshed price is unavailable after that approval, the execution stays queued with retryable true so the same execution can be retried. Nothing further is signed until a fresh quote is available. Shadow executions end at simulated and move no funds.

Current adapter coverage

General swaps support Ethereum, Base, Arbitrum, BNB Chain (BSC), Avalanche and Optimism ERC-20 pairs through LI.FI, including buys and sells without an arbitrage listing. Earn supports listed Morpho V1 and V2 vaults on Ethereum, Base and Arbitrum, using on-chain minimum-share or minimum-asset bounds. Across supports canonical USDC transfers between Ethereum, Base, Arbitrum, Optimism and BNB Chain where live routes exist. THORChain supports available ERC-20 pools on Ethereum, Base, Avalanche and BNB Chain. Aave V3 withdrawals support Ethereum, Base, Arbitrum, Optimism and Avalanche. Supported native ETH routes include ETH.ETH → ETH.WAGMI and BASE.ETH → BASE.WAGMI. Recipients that are not on the wallet transfer allowlist, Aave deposits, CoW, NEAR and Liquidy remain unsupported. Read /capabilities and request a fresh quote for current route availability. Allowlisted ERC-20 transfers use /transfers and count toward the same per-action and daily limits. Capability and eligibility responses identify these cases so your integration can handle them. Select the networks your integration may use in Settings; enable cross-chain and automatic USDC funding separately. Existing grants keep their current permissions. Keep BNB on BNB Chain, AVAX on Avalanche and ETH on the other supported networks for gas.

Optional funding can withdraw Aave USDC and bridge it before trading. All stages share one execution ID and your spending limits. If profitability disappears, the sequence stops and the funded tokens remain in your wallet. See the cross-chain and funding guide for exact requests and recovery behavior.

Different output assets are valued at quote prices. Reported value change is marked to market, not realized cash profit or a guaranteed round-trip return.

Use the general trading client for swap and Earn requests. It persists pending submissions so a restart can reconcile without duplicating the trade.

For automated arbitrage, the example Node.js runner shows how to retain credentials securely and track executions across restarts. Run persistent automations on a host with private environment variables and durable storage.

REFERENCE

REST endpoints

Paths below are relative to the API base. Existing /bot/ authorization paths serve application integrations too; their names remain unchanged for compatibility. Financial amounts are decimal strings; token units are integer strings. Private responses are never publicly cached.

Method	Path	Purpose
POST	`/swaps/quote`	Quote supported same-chain or cross-chain pairs
POST	`/swaps/execute`	Execute a general swap with standing access
POST	`/transfers/quote`	Quote an allowlisted ERC-20 transfer, including gas
POST	`/transfers`	Execute that transfer and return the transaction hash
GET	`/earn/vaults`	Discover Morpho vaults or Aave reserves
GET	`/earn/positions?wallet_id=…`	Read shares and withdrawal liquidity
POST	`/earn/deposit/quote`	Quote an Earn deposit
POST	`/earn/deposit`	Execute the quoted deposit
POST	`/earn/withdraw/quote`	Quote withdrawal by assets or shares
POST	`/earn/withdraw`	Execute the quoted withdrawal
GET	`/me`	Wallet IDs and key permissions
GET	`/capabilities`	Available chains, adapters and execution limits
POST	`/bot/authorizations`	Request owner approval with a bounded policy
POST	`/bot/authorizations/token`	Exchange approved device code for an execution token
POST	`/bot/authorizations/refresh`	Rotate a refresh token for a new short-lived execution token
GET	`/bot/grants/current?wallet_id=…`	Standing or session policy and wallet budgets
DELETE	`/bot/grants/{id}`	Revoke your trading session
GET	`/arbs/active?wallet_id=…&executable_only=false`	Discover opportunities and unsupported reasons
POST	`/arbs/{id}/quote`	Fresh wallet-specific price and profit checks
POST	`/arbs/{id}/execute`	Accept a job using authorized API credentials and Idempotency-Key
GET	`/executions`	Execution history
GET	`/executions/{id}`	Progress, transaction hashes and confirmed settlement
POST	`/executions/{id}/cancel`	Cancel before signing starts
POST	`/executions/{id}/reconcile`	Check a previously submitted transaction
POST	`/executions/{id}/resume or /recover`	Resume bridge delivery/refund observation
GET	`/balances?wallet_id=…`	Spot inventory and wallet reservations
GET	`/volume/today?wallet_id=…`	Settled input volume and gas, by UTC day

General swap request

POST to /swaps/quote using wallet_id, source_asset_id, destination_asset_id, sell_amount and optional slippage_bps. Use full identifiers from /assets. Amounts are decimal strings in whole token units; “1000” means 1,000 tokens. Keep slippage within your grant’s limit.

Download a complete BRETT → USDC example and replace YOUR_WALLET_ID with the wallet ID returned by /me. A 400 response includes error.details with the field and reason. Field aliases such as from_asset and amount_in are not accepted.

Read token balances

Default /balances?wallet_id=… discovers curated tokens and recent activity, including Base BRETT, UNI, and Optimism USDC. Follow next_cursor until null. This is a partial inventory, so an omitted asset does not mean zero. Request any supported ERC-20 directly using repeated asset_id query parameters, up to 30 per request. Quotes also read their source token’s balance directly; they do not depend on the discovery list. Earn positions have their own endpoint.

Retry deliberately

Errors include a stable code, readable message, request_id and retryable flag. Store request IDs for support, without storing credentials.

route_unsupported: skip this opportunity. Do not switch the selected venue behind the owner’s back.
quote_expired / quote_changed: obtain a fresh quote before a new execution.
quote_unavailable after a confirmed approval: keep polling. The execution stays queued and retryable is true. Do not start a second execution for the same order.
authorization_pending: continue polling at the supplied interval.
existing_grant_must_be_revoked: stop polling. Revoke the current wallet grant in Settings, then start a new device-code request.
vault_locked / grant_revoked: enable or restore standing access in Settings; never send a wallet password to the API.
wallet_busy: reconcile the existing execution before another trade.
recovery_required: stop automatic trading and review the execution. Never submit a replacement transaction automatically.