REST API

Base URL: https://api.zerodust.xyz

• JSON in and out. Amounts are strings in wei, chain IDs are numbers.
• No key is needed. An API key raises your rate limits.
• Browsers may only call the API from the ZeroDust site (CORS). Call it from a server, a script or an agent.
• Send only signatures. No endpoint takes a private key.

The SDK wraps the chain, balance, quote and sweep endpoints. Chains without EIP-7702 use separate planning endpoints, documented on Direct chains.

Rate limits

Limits are per client IP and per minute unless noted. With an API key, the read, quote and sweep routes the SDK uses count against the key instead.

Responses carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. Over the limit, the API returns 429:

{ "error": "Too Many Requests", "message": "You are requesting quotes too quickly. Maximum 60 quotes per minute.", "statusCode": 429 }

A wallet address over its sweep limit gets 429 with code RATE_LIMITED.

Errors

Errors are JSON with an error message and, in most cases, a machine-readable code:

{ "error": "Source chain not supported", "code": "INVALID_FROM_CHAIN" }

• 400 with code FST_ERR_VALIDATION: a parameter failed validation.
• 404 "Quote not found", "Sweep not found" and "Chain not found" have no code.
• 500 responses are generic and carry no detail.

Sweep flow

1. GET /quote: price the sweep and get a quoteId.
2. POST /authorization: get the EIP-712 SweepIntent for that quote.
3. Sign the intent, an EIP-7702 delegation to 0x3732398281d0606aCB7EC1D490dFB0591BE4c4f2, and a revoke authorization (delegation to address 0, nonce + 1).
4. POST /sweep: submit the signatures.
5. GET /sweep/:sweepId: poll until completed or failed.

Check the quote before signing it. The SDK's ZeroDustAgent and verifySweepQuote() do this; see Agent.

With MetaMask

A wallet that supports ERC-7715 Advanced Permissions (MetaMask 13.23 or later) can sweep without exposing its key, through the ZeroDust permission router 0x369A97dd256F7eb37fF7116C4EcBd50318eBb286 (same address on every chain it is deployed on). Several chains take one permission request and one signature:

1. wallet_requestExecutionPermissions (in the wallet): per chain, a native-token-allowance of the balance, isAdjustmentAllowed: false, with the rules expiry (the site uses 10 minutes), redeemer = router and payee = router, and to = router. Keep each chain's returned context. The first grant on a chain also upgrades the account to MetaMask's smart account, which spends a little of that chain's balance, so quote after granting.
2. GET /quote?signer=permission per chain.
3. POST /authorization/batch with the quote IDs: the EIP-712 SweepBatch for all of them.
4. Sign it once (eth_signTypedData_v4). The domain has no chain id, so no network switch is needed.
5. For a quote routed through Relay, fetch the deposit from Relay yourself and bind it with POST /quote/:quoteId/relay-route: Relay keeps the recipient on its servers, so only a deposit you requested pays the address you set. Then check intent.callData is exactly that deposit.
6. POST /sweep per quote, each with the same signature, that chain's permissionContext, and batchQuoteIds in the order of step 3.
7. GET /sweep/:sweepId until completed or failed.

The SDK does not support this flow yet. Differences from the key flow:

• No EIP-7702 authorizations from you and no revoke (autoRevoke: false, revokeGasUnits: "0"): the account stays MetaMask's smart account.
• Cross-chain only through Relay, Across, Stargate or Hyperlane, which take the refund address and recipient explicitly. A pair only Gas.zip serves answers PERMISSION_ROUTE_UNAVAILABLE; the key flow can still sweep it.
• A chain's own bridge (bridge=native) is not offered with a permission; sweep with the key.
• Quotes live 55 seconds. If they expire while the wallet is signing, quote again and sign a new batch.

Chains

GET /chains

Chains ZeroDust sweeps with EIP-7702.

Query: testnet (boolean, default false). There are no testnet chains at the moment.

Response:

{
  "chains": [
    {
      "chainId": 8453,
      "name": "Base",
      "nativeToken": "ETH",
      "nativeTokenDecimals": 18,
      "minBalance": "100000000000000",
      "contractAddress": "0x3732398281d0606aCB7EC1D490dFB0591BE4c4f2",
      "explorerUrl": "https://basescan.org",
      "enabled": true,
      "crossChain": { "available": true, "bridges": ["gaszip", "relay", "across"], "checkedAt": "2026-10-01T16:01:01.302Z" },
      "simulation": { "reliable": true, "mode": "authorizationList", "checkedAt": "2026-10-01T16:00:51.180Z" },
      "metamask": true
    }
  ]
}

GET /chains/:chainId

One chain, same fields as above. 404 { "error": "Chain not found" } for an unknown ID.

GET /bridges/timing

How long each bridge usually takes to deliver, from real ZeroDust deliveries in the last 14 days. A bridge or pair with fewer than 3 deliveries is left out, so the lists can be empty. Cached for 5 minutes.

{
  "routes": {
    "relay": { "typicalSeconds": 18, "p90Seconds": 41, "samples": 23, "slowLately": false }
  },
  "pairs": {
    "relay:42161": { "typicalSeconds": 16, "samples": 9 }
  }
}

GET /destinations

Chains a cross-chain sweep from fromChainId can deliver native gas to. Any EVM chain a routing bridge serves qualifies, not only ZeroDust chains. This is what bridges advertise; /quote confirms a route live.

Query: fromChainId (required, must be a ZeroDust chain).

{
  "fromChainId": 8453,
  "destinations": [
    { "chainId": 16661, "name": "0G", "nativeSymbol": "0G", "nativeDecimals": 18, "bridges": ["gaszip"], "zerodustChain": false }
  ]
}

zerodustChain is true when the destination is also a ZeroDust source chain. Errors: 400 INVALID_FROM_CHAIN.

Balances

GET /balances/:address

Native balance on every enabled chain.

Query: testnet (boolean, default false).

{
  "address": "0x...",
  "chains": [
    { "chainId": 8453, "name": "Base", "nativeToken": "ETH", "balance": "1200000000000000", "balanceFormatted": "0.0012", "canSweep": true, "minBalance": "100000000000000" }
  ]
}

canSweep is true for any balance above 0. Whether it covers the fees is decided by the quote.

GET /balances/:address/:chainId

One chain, same fields as an entry above. 404 { "error": "Chain not supported" } for an unknown chain.

Prices

GET /prices

USD prices of native tokens, cached for 10 minutes. For display.

{ "prices": { "ETH": 2681.24, "BNB": 765.75 }, "cachedAt": "2026-10-01T16:00:41.686Z", "ttlSeconds": 115 }

GET /prices/:symbol

{ "symbol": "ETH", "priceUsd": 2681.24 }. 404 when no price is available.

Quotes

GET /quote

Prices a sweep and stores the quote. Nothing is signed or sent.

ZeroDust always chooses the route. For a cross-chain sweep it asks every bridge that serves the pair (Gas.zip, Relay, Across, Stargate; Hyperlane, Metalayer or Endurance for the token deliveries) and keeps the highest expected output. Every route delivers the destination's native gas (see What arrives for the token exceptions): Across is asked only when both chains' gas is ETH, and only a plain deposit to a recipient with no contract code (or an EIP-7702 delegation) on the destination is accepted from it. Passing callTarget or callData is refused with CUSTOM_ROUTE_UNSUPPORTED.

Response:

intent.minReceive is the least the contract will accept: equal to estimatedReceive for a same-chain sweep; for a cross-chain sweep, the bridge's expected output less 0.5%, then 5%.

Fees in a quote

The service fee in extraFeeWei is 5% of the balance's USD value under $1, and 1% from $1 with a minimum of $0.05 and a maximum of $0.50.

Errors (400 unless noted):

POST /quote/:quoteId/relay-route

Binds a Relay deposit you requested from Relay yourself into a signer=permission quote routed through Relay. Relay keeps a request's recipient on its own servers and the deposit only names an id, so a route someone else requested cannot be checked; one you requested can.

Request the deposit with POST https://api.relay.link/quote: user and refundTo = the wallet, recipient = the destination, originChainId / destinationChainId, both currencies 0x0000000000000000000000000000000000000000, amount = the quote's bridge.inputAmount, tradeType EXACT_INPUT. Check Relay's answer (one transaction on the source chain for exactly that amount, details.recipient, native currencyOut on the destination, at least estimatedReceive), then send its transaction here.

Body: { "callTarget": "<tx.to>", "callData": "<tx.data>", "requestId": "<Relay's request id>" }

Returns { quoteId, intent }, the quote's intent now carrying that deposit (callTarget, callData, routeHash). Sign only if intent.callData is the deposit Relay gave you.

Errors (400): NOT_RELAY_ROUTE, PERMISSION_ONLY (key quotes keep their route), ROUTE_ALREADY_BOUND (one bind per quote), QUOTE_EXPIRED, QUOTE_USED (already swept), INVALID_RELAY_ROUTE (not a Relay contract on the source chain, a depository deposit crediting another wallet, a multicall refunding to a third party, or a deposit that would fail from the wallet), ROUTE_GAS_CHANGED (its gas no longer fits the quote's fee reserve: quote again). 404 when the quote does not exist.

POST /authorization

Returns the EIP-712 typed data for a quote.

Body: { "quoteId": "<uuid>" }

Errors: 404 "Quote not found", 400 QUOTE_EXPIRED, 400 CONTRACT_NOT_DEPLOYED.

For a signer=permission quote, typedData is a SweepBatch of that one chain and contractAddress is the router. Use POST /authorization/batch to cover several chains with one signature.

The SweepIntent type is mode uint8, user address, destination address, destinationChainId uint256, callTarget address, routeHash bytes32, minReceive uint256, maxTotalFeeWei uint256, overheadGasUnits uint256, protocolFeeGasUnits uint256, extraFeeWei uint256, reimbGasPriceCapWei uint256, deadline uint256, nonce uint256. Build it from the verified quote and compare it with this response rather than signing the response as received.

POST /authorization/batch

Returns one EIP-712 SweepBatch for several signer=permission quotes, one per chain.

Body: { "quoteIds": ["<uuid>", ...] }, 1 to 64 quotes, in the order you want signed.

Errors (400): INVALID_BATCH (a quote missing or listed twice, not a signer=permission quote, another wallet, or the same chain twice), QUOTE_EXPIRED (quote again).

Rebuild each SweepIntent from its verified quote and compare before signing, as for a single quote.

Sweeps

POST /sweep

Submits a signed sweep. The relayer simulates it, sends it, then sends the revoke.

Body:

| permissionContext | Required with signer=permission, and only then: the context the wallet returned for this chain's permission. It must hold one delegation, from this wallet, to the router. | | batchQuoteIds | signer=permission only: every quote the signature covers, in the order of POST /authorization/batch. Defaults to this quote alone. |

{ "sweepId": "6f1c...", "status": "pending", "sweepType": "cross-chain", "isExisting": false, "version": 3 }

Idempotent per quote: submitting a quoteId that already has a sweep returns that sweep with isExisting: true.

Errors (400 unless noted):

GET /sweep/:sweepId

completed and failed are final. Confirm the result on-chain: the source balance is 0, the wallet has no code once the revoke lands, and the funds arrived.

GET /sweeps/:address

Sweeps for a wallet, newest first.

Query: limit (1 to 100, default 20), offset (default 0), status (one of the statuses above).

{ "sweeps": [{ "sweepId": "...", "status": "completed", "sweepType": "same-chain", "mode": 0, "fromChainId": 8453, "toChainId": 8453, "amountSent": "...", "txHash": "0x...", "version": 3, "createdAt": "..." }], "total": 1 }

API keys

A key gives you your own rate limit, separate from your IP's. Send it as X-API-Key: <key> (what the SDK and MCP server send) or Authorization: Bearer <key>. Treat a key as a secret; it cannot move funds.

• Where it applies: the reads /chains, /chains/:chainId, /destinations, /balances/*, GET /sweep/:sweepId and /sweeps/:address, plus /quote, POST /authorization and POST /sweep. Each route has its own per-minute bucket for the key, at the key's limit (300 for agent keys) and never below the anonymous limit. The 60 sweeps per minute per wallet address still apply.
• Where it does not: /prices and the /direct/* routes keep the per-IP limits.
• One IP, at most two keys an hour. Further keys used from the same IP get that IP's anonymous limits.
• An invalid, revoked or expired key is treated as no key: the request gets the anonymous limits, not an error. Check a key with GET /agent/me.
• A revoked key can keep its higher limits for up to a minute.

POST /agent/register

Issues a key. Limited to 5 per IP per hour.

Response (201): apiKey (shown once, not retrievable later), keyPrefix, keyId, keyType (agent), rateLimits (perMinute 300, daily 1000) and message.

GET /agent/me

Requires a key. Returns keyId, keyType, agentId, rateLimits (perMinute, daily, dailyUsed, dailyRemaining) and stats for the last 7 days (totalRequests, successfulRequests, failedRequests, avgResponseTimeMs).

DELETE /agent/key

Requires a key. Revokes it permanently.

Requests to these routes count against the key's own per-minute limit (300 for agent keys) as well as the IP limit. Missing or invalid key: 401.

MCP and discovery

Health

• GET /health: { "status": "ok", "timestamp": "..." }.
• GET /ready: also checks the database. 200 { "status": "ok", "database": "connected", "timestamp": "..." }, or 503 with database: "disconnected".