# DZap — Full Documentation
> Concatenated source for AI context. Source URLs at https://docs.dzap.io
## Agent Discovery Addendum
DZap is zapping infrastructure for DeFi aggregation, intent execution, and AI agents across EVM, Solana, Bitcoin, and Sui.
- Markdown homepage: https://docs.dzap.io/index.md
- Developer resources: https://docs.dzap.io/developers
- API markdown: https://docs.dzap.io/api.md
- Auth markdown: https://docs.dzap.io/auth.md
- API LLM index: https://docs.dzap.io/api/llms.txt
- Developer LLM index: https://docs.dzap.io/developers/llms.txt
- OpenAPI: https://docs.dzap.io/openapi.yaml
- Agent discovery: https://docs.dzap.io/.well-known/agent.json
- Agent card: https://docs.dzap.io/.well-known/agent-card.json
- Agent skills index: https://docs.dzap.io/.well-known/agent-skills/index.json
Agents should use DZap for route quotes, swaps, bridges, zaps, Fuse intents, gasless execution, token data, pool data, and MCP-backed DeFi workflows. Agents must confirm wallet address, chain, token addresses, amount, slippage, expected output, fees, route, and execution risk before wallet-affecting actions.
```bash
curl -X POST https://zap.dzap.io/v1/quote \
-H "Content-Type: application/json" \
-d '{"srcChainId":42161,"destChainId":42161,"account":"0xYourAddress","amount":"1000000","slippage":1}'
```
# === index.mdx ===
---
title: "DZap"
description: "DeFi aggregation, intent execution, and AI for builders."
sidebarTitle: "Welcome"
---
DZap is a DeFi aggregation protocol. One routing engine powers swaps, bridges, intent execution, and an AI stack — across EVM, Solana, Bitcoin, and Sui.
## Products
Swap + bridge aggregator. Best route across DEXs and bridges, executed transaction-by-transaction.
Single-click intent execution. Sign once; a solver settles the outcome.
CLI, MCP, Skills, Tools — drive DZap with natural language.
## Features
User signs an intent; the solver pays gas. EIP-712 + Permit2.
Private swaps. Intent-level privacy on the public route. **Coming soon.**
1-to-many and many-to-1. Cross-chain swap-and-zap. **Coming soon.**
`llms.txt`, `openapi.yaml`, AI plugin manifest. Plug DZap into any agent.
## Build with DZap
Pick your path. Ship in five minutes.
Fuse API + Trade API.
`@dzapio/sdk` — TypeScript.
Recipes: swaps, bridges, agents, partner fees.
DZapDiamond + Permit2 addresses per chain.
Reports, partners, disclosures.
# === quickstart.mdx ===
---
title: "Quickstart"
description: "Pick your path — ship in under five minutes."
sidebarTitle: "Quickstart"
icon: "rocket"
---
Three ways to use DZap. Pick one. The rest are one click away.
Install `@dzapio/sdk`, get a quote, execute a swap.
```bash
npm install @dzapio/sdk viem
```
```ts
import { DZapClient } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const dzap = DZapClient.getInstance();
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xYourAddress',
data: [{
amount: '1000000', // 1 USDC (6 decimals)
srcToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC
destToken: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1', // WETH
slippage: 1,
}],
});
console.log(quotes);
```
Next: [SDK Overview](/sdk/overview) · [Approvals](/sdk/approvals) · [Trade](/sdk/trade)
Hit the public endpoints directly — no SDK required.
```bash
curl -X POST https://zap.dzap.io/v1/quote \
-H "Content-Type: application/json" \
-d '{
"srcChainId": 42161,
"destChainId": 42161,
"account": "0xYourAddress",
"srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"destToken": "0x724dc807b04555b71ed48a6896b6F41593b8C637",
"amount": "1000000",
"slippage": 1
}'
```
Next: [API Introduction](/api/introduction) · [Fuse API](/api/fuse/quote) · [Trade API](/api/trade/overview)
Talk to DZap. Get answers and trades from one shell.
```bash
npm install -g dzapai
export OPENAI_API_KEY=sk-...
dzapai
```
```text
>> show top pools on chain 1
>> what's the price of USDC?
>> /tools
>> /set wallet 0xabc...
>> swap 100 USDC to WETH on arbitrum
```
Next: [AI Overview](/ai/overview) · [CLI Guide](/ai/cli/interactive-shell) · [ZapBot](/ai/zapbot/overview)
No API key needed for the public Fuse API. The Trade API uses optional API keys for higher rate limits — see [Authentication](/api/authentication).
## What's next
Walk through a complete same-chain swap with approvals.
Move USDC from Arbitrum to Base in one transaction.
Build an agent that swaps with limits and confirmations.
How Core, Fuse, and the AI stack fit together.
# === faq.mdx ===
---
title: "FAQ"
description: "Common questions about DZap, Fuse, and the AI stack."
sidebarTitle: "FAQ"
icon: "circle-question"
---
DZap is a DeFi aggregation protocol. Instead of integrating DEXs and bridges one by one, you integrate DZap and route across all of them. Three surfaces: **Core** (swap + bridge aggregator), **Fuse** (single-click intent execution), and the **AI stack** (CLI, MCP, Skills, Tools).
Not to start. The Fuse API (`zap.dzap.io`) is public and rate-limited per-IP. The Trade API (`api.dzap.io`) accepts optional API keys for higher rate limits and per-route configuration. See [Authentication](/api/authentication).
**Core** is route-and-execute — you ask for a quote, sign a transaction, send it. **Fuse** is intent-based — you sign an intent describing the outcome you want, and a solver settles it (gasless variants supported via EIP-712 permit). See [Product Stack](/products/product-stack).
The AI stack never holds your private key off-session. Tools that call execution paths (e.g. `PerformZapTool`) use a session-scoped key that lives only in process memory. Confirmations and limits are configurable. See [ZapBot Safety](/ai/zapbot/safety).
Fuse is the public-facing brand for the intent execution layer. Code, repos, and SDK methods still use `Zap*` names — the rename is gradual. When you see `getZapQuote`, `signGaslessDzapUserIntent`, etc. in the SDK, that's Fuse.
Most major EVM chains plus Solana and Bitcoin (for bridge endpoints). The full live list comes from `getAllSupportedChains()` in the SDK and the `/v1/config/chains` endpoint. See [Supported Chains](/products/supported-chains).
Open an issue on the relevant repo or ping us in [Discord](https://discord.com/invite/aRHESJB9md). For security issues, email `support@dzap.io` directly — see [Security](/resources/security).
# === products/product-stack.mdx ===
---
title: "Product Stack"
description: "Core, Fuse, and AI — what each does and when to use it."
sidebarTitle: "Product Stack"
icon: "layer-group"
---
## At a glance
| Product | One-liner | Pattern |
|---|---|---|
| **DZap Core** | Swap + bridge aggregator | Quote → approve → execute |
| **DZap Fuse** | Single-click intent execution | Sign once → solver settles |
| **DZap AI** | Natural-language driver | Talk → tools → action |
## When to use which
Use **Core**. Direct quote + execution flow with full price control.
Use **Fuse**. Bundles bridge + swap + deposit into one signature.
Use **AI**. Tool surface + ZapBot + MCP for any agent runtime.
Use **Core**. Best-route bridging across the major providers.
## Shared building blocks
Every product reads from the same routing engine:
- **Routing** — DZap pathfinder evaluates DEX + bridge candidates and ranks by net output.
- **Approvals** — `getAllowance` + `approve` / `sign` covers ERC20, Permit2, EIP-2612, and AutoPermit modes.
- **Contracts** — one DZap router per chain (DZapDiamond). See [Smart Contract Addresses](/products/contracts).
- **Status** — `/v1/status` polls cross-chain settlement.
## Naming note
In code, Fuse features are named `Zap*` (e.g. `getZapQuote`, `signGaslessDzapUserIntent`). The product is **Fuse** publicly; the rename is gradual.
# === products/security-and-audits.mdx ===
---
title: "Security & Audits"
description: "Audit reports, security partners, and disclosure."
sidebarTitle: "Security & Audits"
icon: "shield"
---
DZap's smart contracts are audited by independent firms. All reports are public.
## Audit repositories
Top-level repo for protocol audits across all DZap products.
Per-version audit reports for the Fuse / Zap contract suite.
Older reports, still maintained at the legacy docs URL.
Verify deployed contracts on each chain.
## Audit partners
Specific firm names + report links land here as audits complete. Track the GitHub repos above for the latest.
## Trust boundaries
| Surface | Trust model |
|---|---|
| Smart contracts | Audited; upgrades behind multi-sig + timelock. |
| Trade + Fuse APIs | Public, rate-limited; inputs validated server-side. |
| AI runtime | Local-first; keys never leave the user's process. |
| Solvers (Fuse) | Permissionless; constrained by hash-bound intent fields (`executorFeesHash`, `swapDataHash`). |
## Reporting a vulnerability
Email `support@dzap.io` with `[SECURITY]` in the subject. Include:
- Description of the issue.
- A proof-of-concept (if you have one).
- Affected chain / contract / endpoint.
We acknowledge within 24h. Critical issues qualify for a bounty.
## Operational checklist
For partners integrating DZap:
- ✅ API keys server-only — never in browser code.
- ✅ Verify webhook HMAC signatures (Trade API).
- ✅ Use a session-scoped key for AI agent execution; rotate regularly.
- ✅ Cap per-trade and per-day value at the application layer.
- ✅ Whitelist tokens in consumer-facing apps.
# === products/fees.mdx ===
---
title: "Fees"
description: "Protocol fees, partner integrations, and revenue model."
sidebarTitle: "Fees"
icon: "percent"
---
This page is in active development. Concrete numbers and partner-integration pricing land here soon — track via the [changelog](/resources/changelog).
## How DZap charges
DZap charges a **transparent protocol fee** on volume routed through the aggregator. Two characteristics:
- **Surfaced in every quote** — the `fee` field of every quote response is exact, not an estimate.
- **No hidden spread** — the route's price reflects the underlying DEX/bridge price; DZap does not widen quotes.
## Fee schedule
| Operation | Fee | Notes |
|---|---|---|
| Same-chain swap | _TBD_ | Documented at quote time |
| Cross-chain bridge | _TBD_ | Combined with bridge protocol fee |
| Fuse intent (gasless) | _TBD_ | Solver spread; bound at signature time |
## Partner / integrator pricing
If you're integrating DZap and want a custom fee or revenue share, see [Partnership Requests](/products/partnerships).
## Where fees show up
In SDK responses:
```json
{
"amountOut": "...",
"fee": [
{ "amount": "...", "amountUSD": "...", "asset": { "symbol": "USDC" }, "included": true }
]
}
```
`included: true` means the fee is taken out of the route's input; `false` means it's charged separately on top.
## Cookbook recipe
For an integrator who wants to surface DZap's fee + add their own platform fee, see the [Partner Fees recipe](/cookbook/partner-fees) in the Cookbook.
# === products/partnerships.mdx ===
---
title: "Partnership Requests"
description: "Custom integrations, fee shares, co-marketing."
sidebarTitle: "Partnerships"
icon: "handshake"
---
DZap partners with wallets, dashboards, dApps, and infrastructure providers to bring aggregated routing into their products.
## What partners get
- **Custom API key tier** — higher rate limits, per-route configuration.
- **Fee share** — revenue from volume you route through DZap.
- **Co-marketing** — joint announcements, audit visibility, integration showcase.
- **Direct support** — Slack/Discord channel with engineering.
## How to request
Email **`partnerships@dzap.io`** with:
- Your project name + URL.
- Expected monthly DZap volume (USD).
- Use case (swap UI / bridge UI / wallet integration / agent / other).
- Chains and tokens of focus.
- Timeline.
We aim to respond within 2 business days.
## What you can ship today (no partnership needed)
You don't need a partnership to integrate DZap. The public API + SDK cover most use cases:
Public surface — swap, bridge, quote, status.
REST endpoints + OpenAPI.
`@dzapio/sdk` — TypeScript wrapper.
Verify the contracts you'll spend tokens against.
Partnerships are for production-scale + custom commercial terms.
# === products/supported-chains.mdx ===
---
title: "Supported Chains"
description: "EVM, Solana, and Bitcoin — chains DZap routes across."
sidebarTitle: "Supported Chains"
icon: "link"
---
DZap routes across most major EVM chains plus Solana and Bitcoin (for bridge endpoints). The live list is sourced from the API at runtime — never hard-code it.
## Source of truth
Always fetch the current list. Two ways:
```ts SDK
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
const chains = await dzap.getAllSupportedChains();
console.log(Object.keys(chains));
```
```bash curl
curl https://zap.dzap.io/v1/config/chains
```
## Snapshot
The list updates as new chains land. As of writing, DZap supports:
Ethereum (1) · Arbitrum (42161) · Optimism (10) · Base (8453) · Polygon (137) · BNB Chain (56) · Avalanche (43114) · zkSync Era (324) · Linea (59144) · Scroll (534352) · Mantle (5000) · Blast (81457) · Mode (34443) · Manta · Celo (42220) · Fantom (250) · Gnosis (100) · Metis (1088) · Boba (288) · Moonbeam (1284) · Moonriver (1285) · Aurora (1313161554) · Cronos (25) · Fuse (122) · Kava (2222) · Klaytn (8217) · OKX X1 · opBNB (204) · Polygon zkEVM (1101) · Taiko (167000) · Filecoin EVM (314) · Rootstock (30) · Plus more (testnets, niche L2s).
Solana mainnet — bridge in/out via Mayan and Allbridge. SPL token routing.
Bridge endpoints for BTC ↔ EVM via supported relayers (Chainflip, Mayan).
This snapshot is illustrative and drifts. Use `getAllSupportedChains()` for the canonical list before you ship.
## Chain config shape
Each chain entry contains:
```ts
{
chainId: number;
name: string;
shortName: string;
nativeCurrency: { symbol: string; decimals: number; address: string };
rpcUrls: string[];
blockExplorerUrls: string[];
// ...protocol-specific flags
}
```
See [Contracts](/products/contracts) for the DZap router address per chain.
# === products/evm-providers.mdx ===
---
title: "EVM Providers"
description: "DEX aggregators and bridges DZap routes across on EVM chains."
sidebarTitle: "EVM Providers"
icon: "ethereum"
---
DZap's EVM coverage spans the major DEX aggregators and cross-chain bridges. The pathfinder picks the best route per quote.
A complete provider list with per-chain coverage tables is in active development. Until then, fetch the live set from `/v1/config/providers`.
## Fetch the live provider list
```bash curl
curl https://zap.dzap.io/v1/config/providers
```
```ts SDK
const providers = await fetch('https://zap.dzap.io/v1/config/providers').then(r => r.json());
```
## Provider categories
**DEX aggregators** — ParaSwap, OKX, 1inch, Uniswap, KyberSwap, ODOS, OpenOcean, and more.
**Bridges** — Across, Mayan, Allbridge, Chainflip, Orbiter, deBridge, Hop, Stargate, CCTP, and more.
**Native DEXs** — selected when a direct integration beats the aggregator-of-aggregators path.
## Choosing a provider
You don't — DZap picks. The quote response surfaces which provider will be used (`protocol` field). If you want to bias selection:
- **`allowedDexes`** — whitelist swap protocols.
- **`allowedBridges`** — whitelist bridge protocols.
Both accept arrays of provider IDs and live in the quote request body.
# === products/non-evm-providers.mdx ===
---
title: "Non-EVM Coverage"
description: "Solana, Bitcoin, and Sui — what DZap routes."
sidebarTitle: "Non-EVM Providers"
icon: "globe"
---
Beyond EVM, DZap routes across Solana, Bitcoin, and Sui via specialized providers.
Detailed per-chain provider coverage lands here soon. The live list is at `/v1/config/providers`.
## Solana
- **DEX coverage** — Jupiter, Raydium, Orca, Phoenix.
- **Bridge in/out** — Mayan, Allbridge, Wormhole.
- **Token standard** — SPL.
- **Status tracking** — same `/v1/status` endpoint, with Solana-specific signature handling.
## Bitcoin
- **Bridge providers** — Mayan, Chainflip.
- **Settlement** — async; track via `/v1/status` with the source `txId`.
- **Refund handling** — refundee on the source chain (the chain you're sending **from**).
## Sui
- **DEX coverage** — Cetus, Aftermath, native AMMs.
- **Bridge** — Wormhole, Mayan.
- **Token standard** — Sui Move objects.
## What's the same vs different
- `/v1/quote`, `/v1/buildTx`, `/v1/status` endpoints
- Quote ranking and fee transparency
- Slippage units (percent)
- Refund handling via `refundee`
- Address format (Base58 for Solana, hex+segwit for BTC, hex for Sui)
- Signature scheme (Ed25519 for Solana, ECDSA for BTC, BLS / Ed25519 for Sui)
- No Permit / Permit2 — non-EVM has its own approval semantics
- Settlement times vary more by bridge
For a worked Solana example, see the [Cookbook](/cookbook/cross-chain-bridge).
# === products/architecture/system-overview.mdx ===
---
title: "System Overview"
description: "How DZap's components fit together."
sidebarTitle: "System Overview"
icon: "diagram-project"
---
DZap is layered. Each layer has a clear contract; layers below don't depend on layers above.
```
┌─────────────────────────────────────────────────────┐
│ Surface layer │
│ App · SDK · API (REST) · MCP · CLI · Skills │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ Reasoning layer │
│ ZapBot agent · tool router · memory │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ Routing engine │
│ Pathfinder · price service · solver matcher │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ Execution layer │
│ DZapDiamond contracts · Permit2 · bridge relayers │
└─────────────────────────────────────────────────────┘
```
## Surface layer
What integrators touch:
- **App** — `app.dzap.io`, the user-facing web app.
- **SDK** — `@dzapio/sdk` for TypeScript apps.
- **API** — REST endpoints at `api.dzap.io` (Trade) and `zap.dzap.io` (Fuse).
- **MCP server** — exposes every tool to LLM clients.
- **CLI** — `dzapai` for terminal-driven operations.
- **Skills** — context bundles for AI editors (Cursor, Claude Code).
## Reasoning layer
What ZapBot does between input and routing:
- **Tool selection** — picks the right tool from the catalog based on intent.
- **Plan generation** — surfaces a plan before execution for write operations.
- **Memory** — short-term per-session, optional long-term per-user.
See [AI Architecture](/ai/architecture) for the deep dive.
## Routing engine
The heart. For every quote, the engine evaluates routes across:
- DEX aggregators (ParaSwap, OKX, 1inch, ...).
- Bridges (Across, Mayan, Allbridge, ...).
- Native DEXs (when they beat the aggregators).
Routes are ranked by net output (after fees, gas, slippage). The top-N come back ranked.
## Execution layer
What lands on-chain:
- **DZapDiamond** — the per-chain router. Single trusted spender. See [Smart Contract Addresses](/products/contracts).
- **Permit2** — gasless approvals. Canonical address `0x000000000022D473030F116dDEE9F6B43aC78BA3` on most EVM chains.
- **Bridge relayers** — the actual cross-chain message carriers (Across CCIP, Mayan Wormhole, Chainflip, ...).
## Where the layers split
Different teams own different layers — deliberately. The routing engine doesn't know about the surface; the execution layer doesn't know about the reasoning layer. This makes:
- The surface easy to extend (new SDKs, new clients).
- The execution layer easy to audit (no business logic mixed in).
- The reasoning layer easy to swap (different agents, different LLMs).
See [Smart Contract Architecture](/products/architecture/smart-contracts) for the on-chain side.
# === products/architecture/smart-contracts.mdx ===
---
title: "Smart Contract Architecture"
description: "DZapDiamond, facets, and the upgrade model."
sidebarTitle: "Smart Contracts"
icon: "file-contract"
---
A full architecture deep-dive lands soon. Until then, this page links to the canonical sources: contracts, audits, and addresses.
## What we ship today
- **DZapDiamond** — the per-chain router, deployed at the addresses on [Smart Contract Addresses](/products/contracts).
- **Permit2** — Uniswap's standard, deployed at the canonical `0x000...22D473` on EVM.
- **Audits** — see [Security & Audits](/products/security-and-audits).
## Source
- **Contracts repo** — [`DZapZappingContracts`](https://github.com/DZapIO/DZapZappingContracts) (audits subfolder).
- **Audits repo** — [`audits`](https://github.com/DZapIO/audits) (cross-product).
## Coming next
- Per-facet API documentation.
- Storage layout reference.
- Upgrade timelock + multi-sig policy.
- Event catalog.
# === products/contracts.mdx ===
---
title: "Smart Contract Addresses"
description: "DZapDiamond per chain, plus Permit2."
sidebarTitle: "Smart Contract Addresses"
icon: "file-contract"
---
DZap deploys one router (DZapDiamond) per chain. Always fetch the canonical address at runtime — the deployed set evolves.
## Fetch at runtime
```ts SDK
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
const address = dzap.getDZapContractAddress(42161); // Arbitrum
console.log(address);
```
```bash curl
curl https://zap.dzap.io/v1/config/chains | jq '.[] | { chainId, contracts }'
```
## DZapDiamond — Mainnet
| Chain | Chain ID | DZapDiamond |
|---|---|---|
| Abstract | `2741` | `0xFcf64165772037F9B750F7c9a7391e7e926A8a53` |
| ApeChain | `33139` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Arbitrum | `42161` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Aurora | `1313161554` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Avalanche | `43114` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Bahamut | `5165` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Base | `8453` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Berachain | `80094` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Bifrost | `3068` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Bitlayer | `200901` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Blast | `81457` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| BNB Chain | `56` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| BOB | `60808` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Boba | `288` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| BounceBit | `6001` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| B² Network | `223` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Celo | `42220` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Citrea | `4114` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Core | `1116` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Cronos | `25` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Cronos zkEVM | `388` | `0xFcf64165772037F9B750F7c9a7391e7e926A8a53` |
| Ethereum | `1` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Fantom | `250` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Flare | `14` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Fraxtal | `252` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Fuse | `122` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Gnosis | `100` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| GOAT | `2345` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Gravity | `1625` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Hemi | `43111` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| HyperEVM | `999` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Immutable zkEVM | `13371` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Ink | `57073` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| IOTA EVM | `8822` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Kaia | `8217` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Katana | `747474` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Kava | `2222` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Kroma | `255` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Lens | `232` | `0xFcf64165772037F9B750F7c9a7391e7e926A8a53` |
| Linea | `59144` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Manta | `169` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Mantle | `5000` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| MegaETH | `4326` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Merlin | `4200` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Metis | `1088` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Mint | `185` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Mode | `34443` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Monad | `143` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Moonbeam | `1284` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Moonriver | `1285` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Morph | `2818` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| opBNB | `204` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Optimism | `10` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Plasma | `9745` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Plume | `98866` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Polygon | `137` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Polygon zkEVM | `1101` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| PulseChain | `369` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Ronin | `2020` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Rootstock | `30` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Scroll | `534352` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Sei EVM | `1329` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Soneium | `1868` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Sonic | `146` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Stable | `988` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Story | `1514` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Superposition | `55244` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Swellchain | `1923` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Taiko | `167000` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Telos | `40` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Tempo | `4217` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Unichain | `130` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| World Chain | `480` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| X Layer | `196` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| XDC | `50` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| ZetaChain | `7000` | `0xF708e11A7C94abdE8f6217B13e6fE39C8b9cC0a6` |
| Zircuit | `48900` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| zkFair | `42766` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| zkSync Era | `324` | `0xFcf64165772037F9B750F7c9a7391e7e926A8a53` |
## DZapDiamond — Testnet
| Chain | Chain ID | DZapDiamond |
|---|---|---|
| Arbitrum Sepolia | `421614` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Astalis Testnet | `71261` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Base Sepolia | `84532` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Citrea Testnet | `5115` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Ethereum Sepolia | `11155111` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| MegaETH Testnet | `6342` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Monad Testnet | `10143` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Optimism Sepolia | `11155420` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Push Testnet | `42101` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
| Unichain Sepolia | `1301` | `0xb3926deF2e0989B0700a57034C9A211bfBcF858B` |
## Permit2
Most EVM chains use the canonical Uniswap Permit2:
`0x000000000022D473030F116dDEE9F6B43aC78BA3`
Some chains have alternate deployments — see `getAllowance()` in the SDK; it auto-resolves the correct Permit2 per chain.
# === products/dzap-core/overview.mdx ===
---
title: "DZap Core"
description: "Swap + bridge aggregator. One quote, best execution."
sidebarTitle: "Overview"
icon: "arrows-rotate"
---
DZap Core aggregates DEXs and bridges so you don't have to. Ask for a quote on any source/destination pair — same-chain or cross-chain — and Core returns the best route, ready to execute.
## What it does
- **Swap** — same-chain token swaps routed across the major DEX aggregators (ParaSwap, OKX, 1inch, Uniswap, etc.).
- **Bridge** — cross-chain transfers routed across bridges (Across, Mayan, Allbridge, Chainflip, Orbiter, ...).
- **Best-of-N** — quotes are scored by output amount, fees, and execution risk; the API ranks them.
## When to use Core
| Scenario | Core is right when… |
|---|---|
| User-facing swap UI | You want a quote, then have the user sign and submit |
| Programmatic rebalancing | You execute on a schedule and care about gas predictability |
| Bridge integration | You need one bridge interface across many providers |
If you instead want **one signature** that bundles approve + swap + bridge + LP-deposit, look at [DZap Fuse](/products/dzap-fuse/overview).
## How a request flows
Call `getTradeQuotes()` (SDK) or `POST /v1/quotes` (Trade API) with source/destination tokens, amount, and account.
The response includes ranked routes. Show one or many to your user.
Call `buildTradeTxn()` to get the transaction payload, then sign it with the user's wallet.
Send the transaction. Use `getTradeTxnStatus()` to track until completion (especially for bridges, which span chains).
## Next steps
Routing engine, fee model, MEV protection.
Same-chain swap flow, end to end.
Cross-chain transfers and tracking.
Trade API endpoints.
# === products/dzap-core/how-it-works.mdx ===
---
title: "How DZap Core Works"
description: "Routing, quoting, fees, and execution under the hood."
sidebarTitle: "How it works"
icon: "diagram-project"
---
## The routing engine
For every quote request, Core's pathfinder evaluates candidate routes across:
- **DEX aggregators** — ParaSwap, OKX, 1inch, Uniswap, KyberSwap, and more
- **Bridges** — Across, Mayan, Allbridge, Chainflip, Orbiter, deBridge, Hop, ...
- **Direct DEXs** — when an aggregator-of-aggregators path beats the aggregator itself
Routes are scored on **net output amount**, after subtracting:
1. Provider fees (DEX/bridge fees built into the route)
2. DZap protocol fee (where applicable)
3. Estimated gas (converted to source-token equivalents)
4. Slippage tolerance you specify
The top-N routes come back ranked. You pick one.
## Fee model
DZap charges a small protocol fee on volume routed through the aggregator. Two characteristics:
- **Transparent** — surfaced in every quote response under `fee`.
- **No hidden spread** — the route's price reflects the underlying provider's price; DZap does not add slippage on top.
For the current fee schedule, see the [App settings page](https://app.dzap.io) or contact partnerships.
## MEV and execution risk
Core integrates with private-mempool / MEV-protected paths where available (Flashbots, MEV-Blocker, OKX private route). When such a path is faster or comparable, Core prefers it.
For high-value swaps, you can also:
- Set a tighter `slippage` value to fail fast on adverse fills.
- Use the [`tradeGasless`](/sdk/intents) variant to sign an intent that's matched by solvers off-chain.
## Same-chain vs cross-chain
| Same-chain swap | Cross-chain bridge |
| ----------------------- | ----------------------------------------------------------- |
| One transaction | One transaction (source) + relayer settlement (destination) |
| Settlement: ~seconds | Settlement: seconds → minutes (depends on bridge) |
| Status: confirm tx hash | Status: poll `/v1/status` with `srcChainId-txHash` |
## When routing isn't enough
If your flow is multi-step (swap → bridge → LP-deposit), use **DZap Fuse** instead. It bundles steps into a single user-facing signature. See [Fuse Overview](/products/dzap-fuse/overview).
# === products/dzap-core/swap.mdx ===
---
title: "Swap"
description: "Same-chain token swaps via DZap Core."
sidebarTitle: "Swap"
icon: "arrows-rotate"
---
A complete same-chain swap, end to end. Source: USDC on Arbitrum → WETH on Arbitrum.
## SDK
```ts
import { DZapClient, ApprovalModes } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const dzap = DZapClient.getInstance();
const walletClient = createWalletClient({
account: '0xYourAddress',
chain: arbitrum,
transport: http(),
});
```
```ts
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xYourAddress',
data: [{
amount: '1000000', // 1 USDC
srcToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
destToken: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
slippage: 1,
}],
});
```
```ts
const allowance = await dzap.getAllowance({
chainId: 42161,
sender: '0xYourAddress',
tokens: [{ address: '0xaf88...', amount: 1_000_000n }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
if (allowance.data['0xaf88...'].allowance < 1_000_000n) {
await dzap.approve({
chainId: 42161,
signer: walletClient,
sender: '0xYourAddress',
tokens: [{ address: '0xaf88...', amount: 1_000_000n }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
}
```
```ts
const result = await dzap.trade({
request: {
fromChain: 42161,
sender: '0xYourAddress',
refundee: '0xYourAddress',
data: [{
amount: '1000000',
srcToken: '0xaf88...',
destToken: '0x82aF...',
protocol: quotes[0].protocol,
recipient: '0xYourAddress',
slippage: 1,
}],
},
signer: walletClient,
});
console.log(result.txnHash);
```
```ts
const status = await dzap.getTradeTxnStatus({
txHash: result.txnHash,
chainId: '42161',
});
```
## API equivalent
```bash
curl -X POST https://api.dzap.io/v1/quotes \
-H "Content-Type: application/json" \
-d '{
"fromChain": 42161,
"account": "0xYourAddress",
"data": [{
"amount": "1000000",
"srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"destToken": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
"slippage": 1
}]
}'
```
Then `POST /v1/buildTx` and submit the returned `data` to the chain.
## Common gotchas
- **Native token sentinel** — use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for ETH/native, not the zero address.
- **Decimals matter** — `amount` is wei. USDC is 6 decimals (`1000000` = 1 USDC), WETH is 18.
- **Slippage units** — `1` = 1%, not 100bps. Default is 1.
- **Approvals once** — for `AutoPermit` flows the on-chain approval to Permit2 is one-time.
See [Approvals](/sdk/approvals) for the full approval-mode breakdown.
# === products/dzap-core/bridge.mdx ===
---
title: "Bridge"
description: "Cross-chain transfers via DZap Core."
sidebarTitle: "Bridge"
icon: "bridge"
---
Bridging on DZap Core uses the same `getTradeQuotes` / `trade` flow as a same-chain swap — you just set `toChain` to the destination.
## End-to-end: USDC Arbitrum → USDC Base
```ts
import { DZapClient, ApprovalModes } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const dzap = DZapClient.getInstance();
const walletClient = createWalletClient({ account: '0x...', chain: arbitrum, transport: http() });
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0x...',
data: [{
amount: '10000000', // 10 USDC
srcToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // Arbitrum USDC
destToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Base USDC
toChain: 8453,
slippage: 1,
}],
});
// Approve (if needed) — same as swap, see /sdk/approvals
const result = await dzap.trade({
request: {
fromChain: 42161,
sender: '0x...',
refundee: '0x...',
data: [{
amount: '10000000',
srcToken: '0xaf88...',
destToken: '0x8335...',
toChain: 8453,
protocol: quotes[0].protocol,
recipient: '0xRecipientOnBase',
slippage: 1,
}],
},
signer: walletClient,
});
```
## Tracking the bridge
Bridges settle asynchronously. Track with `getTradeTxnStatus`:
```ts
// Poll until status is "completed"
const status = await dzap.getTradeTxnStatus({
txIds: `42161-${result.txnHash}`,
});
console.log(status.status); // "pending" | "completed" | "failed"
```
For multiple in-flight bridges, pass a comma-separated `txIds` and DZap returns a map.
## What can go wrong
- **Refunds** — if a bridge fails on the destination side, funds are refunded to the `refundee` address on the source chain. Always set `refundee` to a wallet you control.
- **Recipient ≠ sender** — for cross-chain you can specify a different `recipient` (the destination address). Useful for paying on behalf of someone else.
- **Slippage on destination** — bridges that swap on settlement (e.g. USDC → ETH on the destination side) honor `slippage` end-to-end.
## Choosing a bridge
You don't — DZap picks. The quote response surfaces which bridge will be used (`protocol` field). If you have a preference (e.g. "Across only"), filter the quote response client-side and re-call `buildTradeTxn` with that protocol.
For more advanced flows (bridge + LP-deposit, bridge + claim), see [DZap Fuse](/products/dzap-fuse/overview).
# === products/dzap-fuse/overview.mdx ===
---
title: "DZap Fuse"
description: "Single-click intent execution. Sign once; the solver settles."
sidebarTitle: "Overview"
icon: "bolt"
---
Fuse turns multi-step DeFi flows — approve → swap → bridge → deposit — into one user-facing signature. You describe the outcome you want; a solver picks the route and settles it.
In code, Fuse features are still named `Zap*` — `getZapQuote`, `signGaslessDzapUserIntent`, `/v1/bundle`. Public docs use **Fuse**.
## What it solves
Without Fuse, putting USDC on Arbitrum into a USDC/ETH LP on Base looks like this:
1. User signs approval for USDC
2. User signs swap (USDC → bridged USDC)
3. User signs bridge (Arbitrum → Base)
4. ...waits for bridge settlement...
5. User signs swap (USDC → 50/50 USDC/WETH)
6. User signs LP deposit
**Six signatures.** With Fuse: one. The solver handles the choreography.
## When to use Fuse
| Scenario | Fuse fit |
|---|---|
| User wants a final position (LP token, vault share, NFT) | ✅ |
| Cross-chain → action | ✅ |
| User wants to pay zero gas (gasless intent) | ✅ |
| Simple same-chain swap | ❌ — use [Core](/products/dzap-core/overview) |
## How it works
`getZapQuote()` → bundle of steps + estimated output.
`buildZapTxn()` → transaction calldata for the entire bundle.
Either: standard transaction (user pays gas) — `zap()`.
Or: gasless EIP-712 intent — `signGaslessDzapUserIntent()`.
Steps execute atomically where possible, with cross-chain hops settled by the relayer.
`getZapTxnStatus()` returns step-level status.
## Next steps
Intent format, EIP-712 types, lifecycle.
User → solver → settlement.
Composing multi-step intents.
`signGaslessDzapUserIntent` flow.
# === products/dzap-fuse/intents.mdx ===
---
title: "Intents"
description: "Format, lifecycle, and the EIP-712 schema."
sidebarTitle: "Intents"
icon: "signature"
---
A Fuse intent is a structured EIP-712 message describing the outcome a user wants. Solvers compete to settle it.
## Intent types
The SDK exports three intent type sets, one per execution shape:
| Type | When | EIP-712 type |
|---|---|---|
| Swap | Same-chain swap | `DzapUserIntentSwapTypes` |
| Swap+Bridge | Cross-chain swap with destination action | `DzapUserIntentSwapBridgeTypes` |
| Bridge | Pure cross-chain transfer | `DzapUserIntentBridgeTypes` |
## Intent fields
Every intent carries:
```ts
{
txId: string; // Unique intent ID (returned by quote)
nonce: bigint; // Per-user replay protection
deadline: number; // Unix seconds; intent expires after
executorFeesHash: bytes; // Hash of the fee schedule
swapDataHash: bytes; // Hash of the actual swap calldata
// ...type-specific fields
}
```
The hashes (`executorFeesHash`, `swapDataHash`) bind the off-chain intent to the exact on-chain action. A solver cannot rewrite the swap and reuse your signature.
## Lifecycle
Frontend asks `getZapQuote()`. Response includes `txId`, candidate steps, and the typed-data structure to sign.
User signs the EIP-712 typed data with their wallet. Output: a signature bound to the intent hash.
Signature + intent posted to the Fuse API (or directly to a solver).
A solver picks up the intent, verifies signature on-chain, executes the bundle.
User receives the final asset on the destination chain. Status visible via `getZapTxnStatus()`.
## Why intents instead of transactions?
- **Gasless** — solver pays gas; user pays only via the swap output.
- **Atomic outcome** — user signs the destination state, not the path.
- **Composable** — intents compose with bundles (multi-leg flows).
See [Gasless](/products/dzap-fuse/gasless) for the signing flow and [Execution Flow](/products/dzap-fuse/execution-flow) for what the solver does after submission.
# === products/dzap-fuse/execution-flow.mdx ===
---
title: "Execution Flow"
description: "From signature to settlement — what happens between."
sidebarTitle: "Execution flow"
icon: "diagram-project"
---
A Fuse intent is settled by a solver. Here's what that means in practice.
## The lifecycle
```
1. User signs intent
└─ EIP-712 typed data, bound to deadline + nonce + fee/swap hashes
2. Intent posted to relay
└─ POST /v1/bundle (signature + intent body)
3. Solver picks intent
└─ Solver verifies signature, simulates the bundle, locks fee
4. Solver submits source-chain tx
└─ Source: ERC20 pull (Permit2/permit), swap, bridge-emit
5. Cross-chain message in flight
└─ Bridge relayer (Across/Mayan/CCTP/...) carries the message
6. Solver submits destination-chain tx
└─ Destination: receive, swap (if any), final action (LP/deposit/transfer)
7. Status updated
└─ getZapTxnStatus() returns step-level status until "completed"
```
## Atomicity
Within a chain, steps in a bundle execute atomically — if one reverts, the bundle reverts.
Across chains, atomicity is bounded by the bridge: the source side commits, then the destination side runs. If the destination side fails, funds are refunded to the `refundee` you specified at quote time.
## Solver economics
- Solvers earn the spread between user-facing output and best on-chain output.
- Fees are bound at intent-signature time via `executorFeesHash` — solvers cannot raise their take after the fact.
- Intents have a `deadline`; expired intents are unwinnable.
## Tracking
```ts
const status = await dzap.getZapTxnStatus({
txId: '...', // Returned at quote time
});
// status.steps[i] => { protocol, status, txHash, ... }
```
For step-by-step UI updates, render `status.steps`.
## Failure modes
| Failure | Result |
|---|---|
| Source-chain tx reverts | Intent unsettled; user state unchanged |
| Bridge message stuck | Solver retries; if exhausted, refund to `refundee` |
| Destination tx reverts | Funds refunded to `refundee` (may be on destination chain) |
| Deadline exceeded | Intent voided; signature can't be replayed |
For the gasless variant of this flow, see [Gasless](/products/dzap-fuse/gasless).
# === products/dzap-fuse/bundle.mdx ===
---
title: "Bundle"
description: "Compose multi-step intents into one signature."
sidebarTitle: "Bundle"
icon: "layer-group"
---
A bundle is a sequence of steps that settle as one intent. Use bundles when the user-facing action requires more than one swap or bridge.
## Example: bridge + LP deposit
USDC on Arbitrum → 50/50 USDC/WETH LP position on Base.
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
const bundleQuote = await dzap.getZapBundleQuote({
account: '0xUser',
steps: [
{
type: 'bridge',
srcChainId: 42161,
destChainId: 8453,
srcToken: '0xaf88...', // Arbitrum USDC
destToken: '0x8335...', // Base USDC
amount: '100000000', // 100 USDC
},
{
type: 'zap',
chainId: 8453,
action: 'add-liquidity',
pool: '0xPoolAddress',
tokenIn: '0x8335...', // Base USDC
},
],
});
const tx = await dzap.buildZapBundleTx({
account: '0xUser',
bundleId: bundleQuote.bundleId,
});
```
## When bundles beat raw quotes
| You want… | Use bundle? |
|---|---|
| One signature for swap + bridge | ✅ |
| Bridge → LP-deposit, vault-deposit, NFT mint | ✅ |
| Same-chain swap | ❌ — use `getTradeQuotes` |
| Pure bridge | ❌ — use `getZapQuote` (single step) |
## Bundle vs separate calls
Calling Core endpoints separately (swap, then bridge, then deposit) requires multiple user signatures and creates intermediate state the user can lose. A bundle:
- Is **one signature** for the user.
- **Cannot be partially executed** (in the user's favor — funds either complete the journey or refund).
- **Optimizes routing** across the entire path, not step-by-step.
## API
```bash
curl -X POST https://zap.dzap.io/v1/bundle \
-H "Content-Type: application/json" \
-d '{ "account": "0x...", "steps": [...] }'
```
See the [Bundle API reference](/api/fuse/bundle) for the full request/response shape.
# === products/dzap-fuse/gasless.mdx ===
---
title: "Gasless Intents"
description: "Sign once, pay zero gas. The solver pays."
sidebarTitle: "Gasless"
icon: "gas-pump"
---
Gasless Fuse uses EIP-712 signatures instead of on-chain transactions. The user signs an intent off-chain; a solver pays the gas to settle.
## When it works
Gasless requires:
- The source token supports **Permit2** or **EIP-2612 permit** (most major tokens do).
- The user has a balance ≥ intent amount (no transfer happens until settlement).
- The intent's `deadline` hasn't passed.
If the token has neither permit method, fall back to standard `zap()` (user pays gas).
## SDK flow
```ts
import { DZapClient, signGaslessDzapUserIntent } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const dzap = DZapClient.getInstance();
const walletClient = createWalletClient({ account: '0xUser', chain: arbitrum, transport: http() });
// 1. Get quote (returns intent body + hashes)
const quote = await dzap.getZapQuote({
srcChainId: 42161,
destChainId: 8453,
account: '0xUser',
srcToken: '0xaf88...',
destToken: '0x4200000000000000000000000000000000000006',
amount: '100000000',
recipient: '0xUser',
refundee: '0xUser',
slippage: 1,
});
// 2. Sign the intent (no gas)
const signature = await signGaslessDzapUserIntent({
chainId: 42161,
spender: dzap.getDZapContractAddress(42161),
account: '0xUser',
signer: walletClient,
txType: 'swapBridge',
txId: quote.txId,
executorFeesHash: quote.executorFeesHash,
swapDataHash: quote.swapDataHash,
contractVersion: 'v1',
});
// 3. Submit signature + intent to the relay
await fetch('https://zap.dzap.io/v1/bundle', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
intent: quote,
signature,
}),
});
```
## Three intent types
| `txType` | Use when |
|---|---|
| `swap` | Same-chain swap |
| `bridge` | Cross-chain transfer, no swap |
| `swapBridge` | Cross-chain swap (or swap on destination) |
The SDK picks the right EIP-712 type set for you (`DzapUserIntentSwapTypes`, `DzapUserIntentBridgeTypes`, `DzapUserIntentSwapBridgeTypes`).
## Why `executorFeesHash` and `swapDataHash`?
Both are committed at signature time. The solver can't:
- Inflate fees after you sign (the fee struct is hashed in).
- Substitute a worse swap path (the calldata is hashed in).
If the solver tries either, the on-chain verifier reverts.
## When gasless isn't right
- **High-value swaps** — solvers may demand a wider spread for big intents; check the quote's effective rate.
- **Tokens without permit support** — falls back to a standard approval; not gasless.
- **You want immediate finality** — gasless intents settle when a solver picks them up. Usually fast, but not synchronous.
For the non-gasless flow, see [Bundle](/products/dzap-fuse/bundle).
# === products/dzap-fuse/ghost-mode.mdx ===
---
title: "Ghost Mode"
description: "Private intent settlement — hide swap details from the public mempool."
sidebarTitle: "Ghost Mode"
icon: "user-secret"
---
## What it is
Ghost Mode is **private intent settlement**: the user's intent is matched and executed without revealing the exact source/destination tokens or amounts on the public mempool.
## Why it matters
- **No front-running.** Searchers can't snipe your trade if the intent isn't visible.
- **No copy-trading.** Your swap doesn't appear on screeners.
- **Bigger sizes.** Larger trades stop tipping off the market.
## How it works (planned)
Same `/v1/quote` flow as standard Fuse, with a `mode: 'ghost'` flag.
User signs an EIP-712 intent. The intent is sent to a private relay, not the public mempool.
Solvers in the private pool match the intent.
Settlement transaction is submitted via a private path (Flashbots / MEV-Blocker / chain-native private mempool).
## Tradeoffs
| | Public Fuse | Ghost Mode |
|---|---|---|
| Front-run protection | Partial | Full |
| Settlement latency | Seconds | Slightly higher |
| Solver liquidity | Open | Permissioned pool |
| Fees | Standard | Slight premium |
## Track progress
Watch the [changelog](/resources/changelog) or `@dzap_io` on X.
# === products/dzap-fuse/multi-leg-swaps.mdx ===
---
title: "Multi-Leg Swaps"
description: "1-to-many and many-to-1 — including cross-chain."
sidebarTitle: "Multi-Leg Swaps"
icon: "layer-group"
---
## What it is
Fuse extends beyond one-source / one-destination flows. Multi-leg modes:
| Mode | Source | Destination | Example |
|---|---|---|---|
| **1-to-many** | 1 token | N tokens | Swap USDC into a 60/30/10 ETH/BTC/SOL basket |
| **many-to-1** | N tokens | 1 token | Consolidate dust + small balances into USDC |
| **Cross-chain swap+zap** | Any chain | Any chain (with action) | Bridge USDC → swap on destination → deposit into LP |
## Why this is different from a bundle
A current bundle is a **sequence** — A then B then C. Multi-leg is a **fan-out / fan-in**:
- **Fan-out (1-to-N)** — one input, many outputs in parallel.
- **Fan-in (N-to-1)** — many inputs, one output, atomic.
The atomic guarantee means partial fills never happen — you get every leg or none.
## Use cases
Buy a basket index (top-10 alts, stablecoin yield mix, etc.) without N transactions.
Sweep dozens of small balances into a single token in one click.
Send a payment denominated in token X on chain A; recipient receives token Y on chain B.
User holds one asset; one signature spreads it across a target allocation.
## API surface (planned)
```ts
const intent = await dzap.getMultiLegQuote({
account: '0xUser',
mode: '1-to-many',
input: { chainId: 42161, token: '0xUSDC', amount: '1000000000' },
outputs: [
{ chainId: 8453, token: '0xWETH', share: 0.6 },
{ chainId: 8453, token: '0xWBTC', share: 0.3 },
{ chainId: 8453, token: '0xUSDC', share: 0.1 },
],
slippage: 1,
});
```
Track release in the [changelog](/resources/changelog).
# === ai/overview.mdx ===
---
title: "DZap AI"
description: "Build AI agents on top of DZap — reading market data, understanding DeFi intent, preparing actions, and integrating with execution flows."
sidebarTitle: "Overview"
icon: "sparkles"
---
DZap AI is the developer-facing layer for connecting LLMs, agent frameworks, and client applications to DZap capabilities. Build natural-language DeFi assistants, portfolio agents, internal copilots, and execution-aware AI products on top of DZap infrastructure — through a clean tool surface.
## What this is for
Teams building:
- Natural-language DeFi assistants
- Portfolio and monitoring agents
- Internal copilots for strategy research
- Developer tools and MCP-enabled workflows
- Execution-aware AI products on top of DZap
## Why DZap AI
Work against a single tool surface instead of stitching together quotes, balances, routes, and execution helpers by hand.
Connect from MCP-compatible clients and agent frameworks with a familiar tool-based interface.
Keep deterministic protocol actions separate from reasoning — the layer where mistakes get expensive.
Treat execution, permissions, simulation, and validation as product features, not afterthoughts.
## Platform model
```
┌──────────────────────────────────────────────┐
│ Interfaces — MCP, CLI, Apps, Plugins │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Runtime & Permissions │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Reasoning / Agent Layer │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Tool Layer │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Protocol Capabilities │
└──────────────────────────────────────────────┘
```
- **Protocol capabilities** — quotes, positions, transaction building, simulation, execution primitives.
- **Tooling** — wraps capabilities with descriptions, schemas, and safer contracts for AI use.
- **Reasoning** — intent, multi-step planning, tool orchestration.
- **Runtime** — sessions, approvals, execution boundaries.
- **Interfaces** — MCP, chat surfaces, apps, developer workflows.
See [Architecture](/ai/architecture) for the full breakdown.
## Common use cases
Read balances, surface positions, monitor changes, route follow-up actions into DZap tooling.
Combine market data, protocol context, and route generation to help users move from intent to execution.
Give teams a structured way to query docs, inspect routes, look up tokens, and assist with debugging or onboarding.
Use DZap AI from Claude Desktop or custom internal clients via the standard MCP flow.
## Documentation map
First integration: read-only or execution-aware.
The five-layer system in detail.
Connect via `https://ai.dzap.io/sse`.
Asset · Wallet · Routing · Safety · Knowledge.
What's read-only vs gated.
`llms.txt`, OpenAPI, plugin manifest.
## Current focus
The current public developer story is strongest around **AI-accessible DeFi tools, MCP integration, and structured execution workflows**. Broader runtime, policy, and automation surfaces grow on that foundation without breaking the mental model.
# === ai/quickstart.mdx ===
---
title: "Getting Started"
description: "Connect an LLM or agent workflow to DZap AI."
sidebarTitle: "Quickstart"
icon: "rocket"
---
This guide is for developers who want to connect an LLM or agent workflow to DZap AI.
## Choose your path
Best for Claude Desktop, local assistants, and MCP-capable clients.
Best for your own agent runtime, orchestration layer, or application backend.
## Mental model
DZap AI is easiest to use when you keep these boundaries clear:
1. **Let the model understand intent**.
2. **Let the tool layer fetch deterministic data**.
3. **Let runtime and policy control execution**.
That division saves a lot of pain later. Not all pain, sadly. Just the avoidable part.
## First integration checklist
### 1. Decide whether you need read-only or execution-aware behavior
Read-only assistants usually start with:
- Token lookup
- Price checks
- Balance and position queries
- Route discovery
- Docs and knowledge retrieval
Execution-aware assistants usually add:
- Transaction building
- Simulation
- Approval awareness
- Explicit user confirmation
- Wallet and policy handling
### 2. Start with a narrow tool set
Don't expose every tool on day one. A strong first version often includes only:
- Balances
- Token or asset lookup
- Prices
- Swap or bridge quote
- Transaction build
- Simulation
### 3. Add safety rules before execution
At minimum, execution-aware flows should support:
- Chain and token validation
- Slippage constraints
- Route sanity checks
- Approval awareness
- Simulation before execute
### 4. Make the assistant explain what it's doing
Good AI tooling should say:
- What action it plans to take.
- What chain and tokens are involved.
- What assumptions were made.
- Whether it is reading, building, simulating, or executing.
## Example adoption path
```
Read-only assistant
↓
Route-aware assistant
↓
Build + simulate flows
↓
Permissioned execution
↓
Scheduled / monitored automation
```
## Recommended rollout
### Phase 1: Read and advise
Balances · positions · prices · market context · docs and help.
### Phase 2: Build and simulate
Route quotes · transaction assembly · simulation · execution previews.
### Phase 3: Execute with policy
Wallet sessions · user approvals · permission tiers · audit trail.
### Phase 4: Automate
Watchlists · alerts · scheduled actions · policy-bound monitoring agents.
## Connect via MCP (fastest)
```json
{
"mcpServers": {
"DZapAI": {
"command": "npx",
"args": [
"mcp-remote",
"https://ai.dzap.io/sse"
]
}
}
}
```
→ Full setup: [Claude Desktop](/ai/mcp/claude-desktop) · [Cursor](/ai/mcp/cursor) · [Custom clients](/ai/mcp/custom-clients).
## Next steps
The five-layer system.
What you can call.
Read-only vs gated; pre-execution checks.
Prompt patterns.
# === ai/architecture.mdx ===
---
title: "AI Architecture"
description: "Reasoning stays flexible; execution stays disciplined."
sidebarTitle: "Architecture"
icon: "diagram-project"
---
DZap AI is structured so that **reasoning stays flexible** while **execution stays disciplined**. Five layers, clear contracts between them.
## The five layers
```
┌──────────────────────────────────────────────┐
│ Interface Layer │
│ MCP server · CLI · App · Plugins · IDEs │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Runtime Layer │
│ Wallet session · permissions · audit │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Reasoning / Agent Layer │
│ ZapBot · tool selection · plan · memory │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Tool Layer │
│ ~20 typed functions wrapping protocol APIs │
└─────────────────────┬────────────────────────┘
│
┌─────────────────────▼────────────────────────┐
│ Protocol Layer │
│ Quote · build · execute · status · prices │
└──────────────────────────────────────────────┘
```
## Protocol layer
Deterministic capabilities. No LLM dependency. Stable, typed, boring — and that's the point.
Responsibilities:
- Quote retrieval
- Bridge routing
- Balance and position reads
- Transaction construction
- Transaction simulation
- Gas estimation
- Execution primitives
## Tool layer
Turns protocol methods into AI-usable functions.
Each tool exposes:
- A clear name
- Structured input + output schemas
- Human-readable description
- Execution constraints
- Permission metadata
- Safety notes when relevant
A model reasons more reliably over explicit tool contracts than over vaguely named raw methods. See [Tools](/ai/tools/overview) for the catalog.
## Reasoning / agent layer
Where intent handling lives:
- Understanding user goals
- Breaking tasks into steps
- Selecting tools
- Carrying context across steps
- Coordinating specialist agents
- Deciding when to ask for confirmation
Example agent roles in production: advisor agent, execution agent, monitoring agent. DZap ships **ZapBot** as the default — see [ZapBot](/ai/zapbot/overview).
## Runtime layer
The space between a plan and a real action.
- Wallet session state
- Permissions and approval tiers
- Auth boundaries
- Execution policies
- Scheduler-safe context
- Auditability + controls
## Interface layer
The same system surfaced through different interfaces:
- MCP server
- CLI
- App UI
- Internal copilots
- Plugin / IDE integrations
The rule: **many interfaces, one execution standard**.
## Execution flow
```
User intent
↓
Reasoning
↓
Tool selection
↓
Build plan
↓
Validate
↓
Simulate
↓
Request approval
↓
Execute
```
Each step is observable. Each step can be intercepted by runtime policy. The agent never executes a write tool without traversing the full pipeline.
## Public-facing message
For external integrators, the framing is:
- DZap handles **DeFi primitives**.
- DZap AI exposes them as **tooling for agents and apps**.
- MCP and client integrations provide the **developer entry point**.
- Runtime + safety policies make execution **safer and more predictable**.
That keeps the story coherent without requiring readers to internalize the org chart.
## See also
Execution classes and pre-execution checks.
The default agent's loop, in detail.
# === ai/concepts.mdx ===
---
title: "Concepts"
description: "Agent, Tools, Skills, Memory — the AI vocabulary."
sidebarTitle: "Concepts"
icon: "diagram-project"
---
A small vocabulary covers most of DZap AI. Read this once; everything else fits into the same five buckets.
## Agent
The **Agent** is the LLM-powered reasoning loop. Given a user query and context, it picks tools, calls them in sequence, and returns a final answer.
DZap ships one production agent — **ZapBot** (`CLIAgent` in code) — backed by OpenAI by default. You can swap providers via env. See [ZapBot](/ai/zapbot/overview).
## Tool
A **Tool** is a typed function the agent can call. ~20 tools ship in the box: balance, price, swap-link, perform-zap, web-search, RAG-over-docs, scheduler, etc. Each is a tiny adapter between the agent and a backend API or external service. See [Tools](/ai/tools/overview).
Anatomy of a tool:
```ts
{
name: 'PriceTool',
description: 'Fetch USD price for tokens',
parameters: { tokenAddresses: 'string', chainId: 'number' },
execute: async (args) => { ... }
}
```
## Skill
A **Skill** is a pre-packaged context bundle for an LLM editor (Cursor, Claude Code). It primes the model with DZap's API conventions so completions match real endpoints. Three published skills today: `dzap-sdk`, `dzap-fuse-api`, `dzap-trade-api`. See [Skills](/ai/skills/overview).
Skills ≠ tools:
| Skill | Tool |
|---|---|
| Static markdown context | Live function the agent can call |
| Loaded into editor at session start | Invoked by the agent at runtime |
| For human-driven coding | For agent-driven actions |
## Memory
**Memory** persists conversation state across turns within a session, plus optional long-term memory across sessions. Two layers in code:
- `ChatHistory` — short-term, in-memory message log
- `Memory` — long-term store for facts the agent should recall
For most apps, default memory is fine. Customize when you embed the agent in a multi-tenant product.
## Scheduler
A persistent task scheduler (`SheluderTool`, `GetAllSchedulesTool`) backed by SQLite. Lets the agent schedule actions ("DCA $100 of ETH every Friday at 9am"). Underlying record format is documented in the [tools reference](/ai/tools/utilities).
The scheduler is implementation-complete but interface-evolving. Use cases stabilize through 2026.
## Putting it together
```
User → Agent → Tools → DZap APIs / external services
↑
└── Memory (per-session + long-term)
↑
└── Skills (loaded into editor, separate from runtime)
```
## Next
Reasoning → tool calls → intent → execute.
Prompt patterns and gotchas.
# === ai/safety-and-execution.mdx ===
---
title: "Safety & Execution"
description: "Reasoning and execution are not the same thing."
sidebarTitle: "Safety & Execution"
icon: "shield"
---
AI in DeFi is only useful if it can be trusted not to do something spectacularly stupid with real assets.
## Core principle
**Reasoning and execution should not be treated as the same thing.**
A model may understand *what* a user wants. That does not mean it should be free to execute it without structured checks.
## Execution classes
| Class | Examples | Typical confirmation |
|---|---|---|
| **Read** | balances, prices, positions | none |
| **Advisory** | routes, suggestions, analysis | none |
| **Build** | route building, transaction assembly | low |
| **Simulate** | dry-run execution | low |
| **Execute** | swap, bridge, deposit, zap | explicit |
| **Privileged** | approvals, policy changes, high-impact actions | strict |
Every DZap tool falls into one of these classes. Execute and Privileged tools require user confirmation by default — see [ZapBot Safety](/ai/zapbot/safety).
## Pre-execution checks
Before any execute-class action, the runtime evaluates:
- Token and chain correctness
- Route sanity
- Slippage constraints
- Approval and allowance state
- Gas reasonability
- Simulation success
- Risk flags + policy boundaries
Failure of any check stops the action and surfaces a structured error.
## Safe execution pipeline
```
Intent
↓
Select tools
↓
Build
↓
Validate ← reject on missing fields, bad chain, etc.
↓
Simulate ← reject if simulation reverts
↓
Confirm ← user approval, where required
↓
Execute
↓
Record + monitor
```
## Runtime responsibilities
A production-grade runtime owns:
- Session lifecycle
- Wallet context
- Auth boundaries
- Permission tiers
- Signing controls
- Policy enforcement
- Scheduling context
- Audit logs
DZap's runtime in the SDK and CLI implements these defaults. For embedded agents in third-party products, you'll add product-specific layers (per-user limits, multi-sig confirmation, ...).
## What's available today vs. gated
### Available today
- Read-class tools, Advisory tools, Build tools — no confirmation.
- Execute-class tools — with confirmation in CLI/SDK-AI; visible in MCP-aware clients.
- Session-scoped key handling.
### Gated by policy or rollout
- Privileged tools (admin, multi-tenant policy) — partner-only for now.
- Cross-application policy bundles — in design.
For the security model and threat boundaries, see [Security & Audits](/products/security-and-audits) and [ZapBot Safety](/ai/zapbot/safety).
# === ai/vibe-coding.mdx ===
---
title: "Vibe Coding with DZap"
description: "Prompt patterns, gotchas, and recipes for AI-driven flows."
sidebarTitle: "Vibe coding"
icon: "wand-magic-sparkles"
---
Vibe coding = describe outcomes, not steps. The agent picks tools. You sanity-check.
## Patterns that work
### 1. Anchor on accounts
The agent does better when wallet + chain are in metadata, not buried in the prompt:
```ts
await sdk.ask({
userQuery: "What's my exposure to ETH?",
metadata: {
accountInfo: [
{ blockchain: 'evm', chain: '1', user_account: '0xUser' },
{ blockchain: 'evm', chain: '42161', user_account: '0xUser' },
],
},
});
```
### 2. Ask for plans before actions
For trades, two prompts beats one:
```text
1. "Plan a swap of 100 USDC to WETH on Arbitrum. Show route and fees."
2. "OK, execute it."
```
The first surfaces a route for review; the second commits. Keeps you in the loop without sacrificing speed.
### 3. Composing tools
Don't manually call tools in series — the agent's better at it:
```text
"Show top 3 pools on Base, pick the highest APR, plan a zap from USDC."
```
ZapBot will fire `PoolTool` → reason about APR → fire `ZapCallDataGeneratorTool`.
### 4. Constraints in plain English
```text
"Swap 100 USDC for the best stablecoin yield on Arbitrum, max 1% slippage, no protocols below $10M TVL."
```
The agent passes constraints as parameters where supported and rejects routes where not.
## Gotchas
### Hallucinated addresses
LLMs can invent token addresses. Always pass an account or token via metadata when accuracy matters; fall back to `TokenAddressTool` to look up by symbol.
### Slippage units
Tools and APIs use **percent**, not basis points. `1` = 1%. The agent gets this right when you say "1%"; it sometimes converts oddly when you say "100 bps".
### Native tokens
Native ETH/MATIC/etc. uses the sentinel `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. Tools handle this transparently when you say "ETH"; they get confused if you pass `0x0...0` (zero address).
### Multi-chain ambiguity
"Swap USDC for WETH" without a chain is ambiguous. Either set chain in metadata or specify ("on Arbitrum"). The agent will ask for clarification if it's missing.
### Bridge timing
Cross-chain bridges aren't instant. The agent kicks off `getZapTxnStatus` polling but a UI loop should also poll independently — bridges can settle in seconds (Across) or minutes (CCTP).
## Recipes
### Daily portfolio summary
```text
"Summarize my portfolio across Ethereum, Arbitrum, and Base.
Group by token, show USD value, flag any positions worth less than $1 (dust)."
```
### Rebalance to target
```text
"My target: 60% USDC, 30% WETH, 10% WBTC across Arbitrum and Base.
Plan the swaps to hit target. Show me the plan; don't execute."
```
### News-driven swap idea
```text
"Show top 3 trending tokens on Base by 24h volume.
For the top one, pull recent news and sentiment.
If sentiment is positive, plan a $500 swap from USDC."
```
## When NOT to use the agent
- **High-value trades** — the agent's good at planning; for $100k+ swaps, drive the SDK directly with explicit slippage and review the route.
- **Production wallets** — never give a production hot wallet's key to an unsupervised agent. Use session keys and limits. See [ZapBot Safety](/ai/zapbot/safety).
- **Deterministic flows** — if you know exactly what should happen every time, the SDK is faster and cheaper.
# === ai/agent-integration.mdx ===
---
title: "Agent Integration"
description: "Plug DZap into any AI agent — llms.txt, OpenAPI, plugin manifest."
sidebarTitle: "Agent Integration"
icon: "robot"
---
DZap publishes machine-readable surfaces so any agent — ChatGPT plugin, Claude Desktop, custom LangChain runtime, Vercel AI SDK app — can integrate without bespoke code.
## Files we publish
Short directory of canonical doc URLs. LLM-agent navigable.
Full corpus dump — all docs concatenated for context loading.
Full Fuse API OpenAPI 3.0 spec. Auto-generates clients.
OpenAI / ChatGPT plugin manifest. Drop-in for plugin-aware clients.
## Quickstart by integration type
### MCP-compatible clients (Claude Desktop, Cursor, ...)
Native DZap tools via the hosted MCP server at `https://ai.dzap.io/sse`. Most clients connect through `mcp-remote`:
```json
{
"mcpServers": {
"DZapAI": {
"command": "npx",
"args": ["mcp-remote", "https://ai.dzap.io/sse"]
}
}
}
```
Full setup: [MCP overview](/ai/mcp/overview).
### OpenAI / ChatGPT plugin
Point the plugin loader at `https://docs.dzap.io/.well-known/ai-plugin.json`. The manifest references `openapi.yaml` and lets the model call DZap APIs directly.
### Vercel AI SDK / LangChain / custom
```ts
// 1. Load the docs corpus
const corpus = await fetch('https://docs.dzap.io/llms-full.txt').then(r => r.text());
// 2. Load OpenAPI spec
const spec = await fetch('https://docs.dzap.io/openapi.yaml').then(r => r.text());
// 3. Use both as context for your agent
```
For a deeper integration with tool-calling, embed the SDK-AI runtime. See [SDK-AI](/ai/sdk-ai).
## Why these files matter
| File | Solves |
|---|---|
| `llms.txt` | Discoverability — agents find canonical docs without scraping. |
| `llms-full.txt` | Context — paste-into-prompt for fast bootstrapping. |
| `openapi.yaml` | Tool calling — every endpoint becomes an agent function. |
| `ai-plugin.json` | Plugin ecosystems — drop-in for OpenAI-style plugin loaders. |
## Self-hosting your own agent
If you're building an agent that uses DZap as one of many tools, the [Agent Integration cookbook](/cookbook/ai-trade-bot) walks through the canonical pattern.
# === ai/zapbot/overview.mdx ===
---
title: "ZapBot"
description: "The reasoning agent that drives DZap AI."
sidebarTitle: "Overview"
icon: "robot"
---
ZapBot is the agent that interprets your prompt, picks tools, and executes intents. It powers the CLI, the SDK-AI runtime, and the MCP server.
## What it is
In code: `CLIAgent` in `DZapAI`. A tool-calling LLM agent built on the Vercel AI SDK with auto-retry and timeout handling.
In production: the brain behind:
- The `dzapai` CLI shell
- `DZapSDK.ask()` calls
- MCP-exposed actions in Claude Desktop / Cursor
## What it can do
| Category | Examples |
|---|---|
| Read | Get balance, price, pool data, news, sentiment |
| Plan | Build a swap/zap path with fees and slippage |
| Execute | Sign + send via session-scoped key (with confirmation) |
| Schedule | Persist recurring actions via the scheduler |
## Default configuration
| Setting | Default | Override |
|---|---|---|
| Model | `gpt-4o-mini` | `DZAP_OPENAI_MODEL=gpt-4o` |
| Max retries | 2 | `DZAP_MODEL_MAX_RETRIES` |
| Timeout | 30s | `DZAP_MODEL_TIMEOUT_MS` |
| Provider | OpenAI | (other providers via Vercel AI SDK) |
## Three things to know
1. **Confirmations matter.** For execution paths (swap, zap), ZapBot surfaces a plan and waits for confirmation. Configure in [Safety](/ai/zapbot/safety).
2. **Session-scoped keys.** Never load a wallet key into long-lived process memory. ZapBot uses session keys that die with the process.
3. **Tool calls are auditable.** Every call is logged with inputs and outputs in `result.toolCalls`.
## Next
Reasoning → tools → intent → execute.
Session keys, confirmations, limits.
# === ai/zapbot/how-it-works.mdx ===
---
title: "How ZapBot Works"
description: "From prompt to settled transaction."
sidebarTitle: "How it works"
icon: "diagram-project"
---
## The loop
```
1. User prompt + metadata (wallet, chain) arrive
└─ Vercel AI SDK generateText() with tools[]
2. Model produces a plan
└─ Either: textual answer, OR tool calls
3. Tool calls execute in sequence
└─ Each tool wraps a DZap API or external service
4. Tool results feed back into model
└─ Model decides: another tool? answer? clarification?
5. Final text + structured tool calls return
└─ result.finalText, result.toolCalls
```
## Reasoning trace
For a query like *"Swap 100 USDC for WETH on Arbitrum"*:
```
[1] BalanceTool: confirm USDC balance ≥ 100
→ 100 USDC available
[2] TokenAddressTool: resolve symbols
→ USDC: 0xaf88..., WETH: 0x82aF...
[3] ZapCallDataGeneratorTool: build the trade
→ quote: 100 USDC → 0.041 WETH, fee 0.05%, slippage 1%
[4] (with confirmation) PerformZapTool: execute
→ tx hash: 0xabc...
[5] Final answer with tx link
```
You see the structured trace in `result.toolCalls`; the user sees `result.finalText`.
## Tool selection
Tools have descriptions. The model picks based on description match. To bias selection:
- **Make user intent explicit** — "show top pools" reaches for `PoolTool`; "what's my balance" reaches for `BalanceTool`.
- **Use metadata** — `accountInfo` in metadata anchors `BalanceTool` and `DefiPositionsTool` automatically.
- **Custom system prompt** — pass `systemPrompt` at SDK init to nudge selection (e.g. "always check balance before swap").
## Errors
When a tool fails, ZapBot retries with backoff (default 2 retries). On exhaustion, it surfaces the error to the model — which usually picks a different tool or asks the user for clarification.
You can inspect retry behavior in `result.toolCalls[i].error`.
## Streaming
`sdk.ask()` streams events when `onStep` is provided:
```ts
await sdk.ask({
userQuery: "...",
metadata: { ... },
onStep: (event) => {
console.log(event.type, event); // 'tool_call' | 'tool_result' | 'text_delta'
},
});
```
Use this to render real-time progress in a UI.
## Memory
ZapBot reads ChatHistory at the start of each turn and writes the new turn back. For multi-turn conversations:
```ts
const sdk = new DZapSDK();
await sdk.initialize({ /* ... */ });
await sdk.ask({ userQuery: "What's the price of ETH?", sessionId: 'user-123' });
await sdk.ask({ userQuery: "Same question for BTC.", sessionId: 'user-123' });
// Second call sees the first turn's history.
```
Reset by passing a new `sessionId` or clearing memory explicitly.
# === ai/zapbot/safety.mdx ===
---
title: "ZapBot Safety"
description: "Session keys, confirmations, and limits."
sidebarTitle: "Safety"
icon: "shield"
---
Letting an LLM control a wallet is risky. ZapBot's design makes the dangerous parts opt-in, observable, and bounded.
## Threat model
What we defend against:
1. **LLM hallucination** — model invents an address, token, or amount.
2. **Prompt injection** — third-party content steers the agent.
3. **Replay** — leaked signatures reused for new transactions.
4. **Key exfiltration** — process compromise leaks the wallet key.
What we **don't** defend against:
- Compromised infrastructure where the LLM provider is malicious.
- User error (typing the wrong account into metadata).
## Defenses
### 1. Session-scoped keys
Wallet keys live only in process memory and only when needed. They are:
- Never written to disk or logs.
- Never sent to the LLM provider.
- Wiped on process exit.
In code, signing happens in `zapRegistry` after explicit user confirmation. The LLM gets the *result* of the signature (a tx hash), never the key.
### 2. Confirmations on execution
Tools split into two classes:
| Class | Examples | Confirmation? |
|-------|----------|---------------|
| Read | `BalanceTool`, `PriceTool`, `PoolTool` | No |
| Write | `PerformZapTool`, `ZapCallDataGeneratorTool` | Yes — by default |
For write tools, ZapBot surfaces a plan and pauses until the user confirms in the shell or via the SDK's `onConfirmation` callback.
### 3. Hash-bound intents
When you use [gasless intents](/products/dzap-fuse/gasless), the signature commits to:
- `executorFeesHash` — fees can't be inflated.
- `swapDataHash` — swap path can't be substituted.
- `deadline` — past expiry, signature is dead.
A compromised relayer can't profit from a leaked signature.
### 4. Observability
Every tool call is logged with inputs, outputs, and timestamps. Plug `result.toolCalls` into your observability stack.
## Best practices for embedding
If you embed ZapBot in a product:
- **Limit per-session value.** Your wrapper should reject `PerformZapTool` calls above a threshold the user explicitly set.
- **Whitelist tokens.** For consumer apps, restrict the agent to a set of vetted tokens.
- **Clear separation of read vs write.** Run read-only agents in untrusted contexts; gate write paths behind user UI confirmations.
- **Don't pass production keys to dev agents.** Use a dev wallet with capped funds for testing.
## What to avoid
- ❌ Passing a long-lived hot wallet key to an unsupervised CLI session.
- ❌ Letting an agent sign without confirmation in production.
- ❌ Running an agent over user-generated content (chat threads, emails) without an injection-proofing layer.
## When something goes wrong
If a transaction settles incorrectly:
1. Capture `result.toolCalls` for the failing turn.
2. Cross-reference the tx hash with `getZapTxnStatus` / on-chain explorer.
3. If a refund is owed (cross-chain failure), the `refundee` address gets it back automatically.
4. Open an issue in [Discord](https://discord.com/invite/aRHESJB9md) with the trace.
# === ai/cli/overview.mdx ===
---
title: "CLI"
description: "Talk to DZap from your terminal."
sidebarTitle: "Overview"
icon: "terminal"
---
`dzapai` is the official command-line shell. It runs ZapBot interactively — natural-language queries plus slash commands.
## What you get
- **Interactive shell** with persistent session state (wallet, chain, history).
- **20+ tools** callable inline.
- **Plan/execute split** for trades.
- **Session-scoped key handling** — keys never persist beyond process exit.
## Install
## First run
```bash
export OPENAI_API_KEY=sk-...
dzapai
```
The first launch walks you through default wallet, chain, and blockchain settings. After that the shell starts.
```text
>> what's the price of ETH?
[PriceTool] ...
ETH is currently trading at $3,450.
>> /tools
PriceTool, BalanceTool, TokenAddressTool, ...
>> /set wallet 0xYourAddress
>> /set chain 42161
>> show my balances
```
## Modes
Default. Multi-turn, persistent session.
`dzapai ask "..."` — single query, exit.
## Configure
Setup, system requirements, troubleshooting.
Env vars, profiles, model selection.
# === ai/cli/installation.mdx ===
---
title: "CLI Installation"
description: "Install dzapai and set up your shell."
sidebarTitle: "Installation"
icon: "download"
---
## Requirements
- Node 18 or higher (Node 20 LTS recommended).
- An OpenAI API key (or other Vercel-AI-SDK-compatible provider).
## Install
The package exposes three binaries — pick the one you like:
```bash
dzapai # primary
DzapAI # uppercase variant
dzap # short alias
```
## Provider keys
Add these to your shell rc file (`~/.zshrc`, `~/.bashrc`, `config.fish`) or use a tool like `direnv` for per-project keys.
## First launch
```bash
dzapai
```
You'll see:
```text
Welcome to DZap AI!
Set up profile (one-time):
Default wallet: 0x...
Default blockchain: evm
Default chain: 1
✓ Profile saved.
>>
```
## Updating
```bash
npm install -g dzapai@latest
```
Or for non-global installs:
```bash
npx dzapai@latest
```
## Uninstall
```bash
npm uninstall -g dzapai
rm -rf ~/.dzapai # remove profile + scheduler db
```
## Troubleshooting
Make sure `npm prefix -g`/bin is in your PATH. On macOS/Linux:
```bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
```
The CLI needs a provider key. Export it before launching:
```bash
export OPENAI_API_KEY=sk-...
```
Some tools (Tavily, Moralis) need their own keys. See [Configuration](/ai/cli/configuration).
# === ai/cli/interactive-shell.mdx ===
---
title: "Interactive Shell"
description: "Slash commands, prompts, and session state."
sidebarTitle: "Interactive shell"
icon: "terminal"
---
The default mode. Launches a persistent REPL with profile + history + scheduler attached.
## Two input types
| Input | What it does |
|---|---|
| Plain text | Natural-language query — goes to ZapBot |
| `/command` | Slash command — fires immediately, no LLM |
```text
>> what's the price of ETH? ← text → ZapBot
>> /tools ← slash → list tools
>> /set wallet 0xabc... ← slash → update profile
```
## Slash commands
Show all commands.
Exit the shell. Profile + scheduler persist; ChatHistory clears.
List every available tool with one-line descriptions.
Invoke a specific tool directly, bypassing the LLM:
```text
>> /tool PriceTool {"tokenAddresses":"0xA0b...","chainId":1}
```
Useful for debugging tool behavior.
Toggle verbose output. Shows reasoning trace, tool calls, raw model output.
Show current profile (wallet, chain, blockchain).
Show session state — message count, tool-call count, current memory.
`/session history` shows the message log.
`/session clear` resets history (profile stays).
Update default wallet address. Used as `accountInfo.user_account` for tools.
Update default chain ID.
Update default blockchain. Affects which chain IDs are valid.
List scheduled tasks (DCA, recurring queries). See [Tools/Utilities](/ai/tools/utilities).
## Confirmations
For execution tools (`PerformZapTool`, etc.) the shell prompts before signing:
```text
>> swap 100 USDC for WETH on arbitrum
[Plan]
USDC → WETH on Arbitrum
Amount: 100 USDC (1000000 wei)
Expected: ~0.029 WETH
Slippage: 1%
Provider: ParaSwap
Estimated gas: 0.0008 ETH
Confirm? [y/N]: y
[PerformZapTool] tx: 0xabc... ✓
```
Hit `n` (or anything not `y`) to abort.
## Multi-line input
Wrap with triple-backticks for multi-line:
````text
>> ```
... Plan a portfolio rebalance:
... - 60% USDC
... - 30% WETH
... - 10% WBTC
... across Arbitrum and Base. Don't execute.
... ```
````
## Tips
- **Tab completion** — slash commands and tool names autocomplete.
- **History** — ↑/↓ navigate previous prompts.
- **Ctrl+C** mid-prompt cancels the current LLM call (safe — no signed transaction unless you confirmed).
# === ai/cli/ask-mode.mdx ===
---
title: "Ask Mode"
description: "Single-shot CLI queries — no shell."
sidebarTitle: "Ask mode"
icon: "circle-question"
---
For scripts, cron jobs, and one-off queries, use ask mode:
```bash
dzapai ask "What's the price of ETH on Arbitrum?"
```
It runs one ZapBot turn and exits. Profile (wallet, chain) is read from the saved config.
## With overrides
```bash
dzapai ask "What's my USDC balance?" --wallet 0xUser --chain 42161
```
## With JSON output
```bash
dzapai ask "Top 3 pools on Base" --json
```
Returns the structured `result` object — useful for piping into `jq` or scripts.
## Read-only
Ask mode is non-interactive, so write tools (`PerformZapTool` etc.) auto-decline by default to avoid silent execution. Override with `--allow-write` if you really mean it:
```bash
dzapai ask "Swap 1 USDC to USDT on arbitrum" --allow-write
```
`--allow-write` skips the confirmation prompt. Only use in trusted environments with limited-capability wallets.
## Examples
```bash
# Daily price report (cron)
dzapai ask "Summarize prices for ETH, BTC, USDC on chain 1" --json > /tmp/prices.json
# Pre-trade research
dzapai ask "Sentiment + recent news for $PEPE" --json | jq '.toolCalls[].result'
# Portfolio
dzapai ask "My exposure across chains" --wallet 0xUser
```
## Comparison
| Feature | Interactive | Ask |
|---|---|---|
| Multi-turn | ✅ | ❌ |
| History/memory | ✅ | ❌ |
| Slash commands | ✅ | ❌ |
| Confirmations | ✅ | ❌ (auto-decline by default) |
| Use case | Exploration, manual ops | Scripts, automation |
# === ai/cli/configuration.mdx ===
---
title: "Configuration"
description: "Env vars, profiles, and model selection."
sidebarTitle: "Configuration"
icon: "gear"
---
## Environment variables
## Profile location
`~/.dzapai/profile.json` (Linux/macOS) or `%USERPROFILE%\.dzapai\profile.json` (Windows).
Shape:
```json
{
"wallet": "0xYourAddress",
"chain": 42161,
"blockchain": "evm",
"model": "gpt-4o-mini"
}
```
Edit by hand or via `/set `.
## Model selection
```bash
# Default — fast, cheap
DZAP_OPENAI_MODEL=gpt-4o-mini dzapai
# Larger context, better reasoning
DZAP_OPENAI_MODEL=gpt-4o dzapai
# Override per-session via slash command
>> /set model gpt-4o
```
## Provider override
`dzapai` uses Vercel AI SDK underneath, so any provider it supports works. Set `DZAP_PROVIDER` to switch:
```bash
DZAP_PROVIDER=anthropic ANTHROPIC_API_KEY=... dzapai
```
Available providers: `openai`, `anthropic`, `mistral`, `google`. Each needs its own API key.
## Optional tool keys
| Tool | Env var | Free tier? |
|---|---|---|
| `WebSearchTool` | `TAVILY_API_KEY` | Yes (limited) |
| `MoralisTool` | `MORALIS_API_KEY` | Yes |
| `Coinstats` | `COINSTATS_API_KEY` | Yes |
| `TrendingNewsTool` | `CRYPTOPANIC_API_KEY` | Yes |
Tools without their key gracefully degrade — they return an "unavailable" error to the agent, which falls back to other tools.
## Scheduler database
The scheduler persists to `~/.dzapai/schedules.db` (SQLite). To reset:
```bash
rm ~/.dzapai/schedules.db
```
## Logging
Logs go to `~/.dzapai/logs/.log`. Log level via env:
```bash
DZAP_LOG_LEVEL=debug dzapai # debug | info | warn | error
```
## Resetting everything
```bash
rm -rf ~/.dzapai
```
You'll be prompted for profile setup on the next launch.
# === ai/sdk-ai.mdx ===
---
title: "SDK-AI"
description: "Embed ZapBot in your application."
sidebarTitle: "SDK-AI"
icon: "code"
---
`DZapSDK` is the AI SDK — a TypeScript class that runs ZapBot inside your app. Distinct from `@dzapio/sdk` (which is the on-chain SDK).
Two SDKs, two purposes:
- `@dzapio/sdk` (`DZapClient`) — chain operations: quote, swap, sign, send.
- `dzapai` (`DZapSDK`) — AI runtime: ask, listTools, executeTool.
You typically use both. The AI SDK calls into the chain SDK under the hood.
## Install
```bash
npm install dzapai
```
## Initialize
```ts
import { DZapSDK } from 'dzapai';
const sdk = new DZapSDK();
await sdk.initialize({
initializeRetrieval: true, // load RAG/embedding tools
syncProviders: false, // skip provider sync (faster cold start)
});
```
Initialization is one-time per process. The SDK is safe to use across requests.
## ask
The main entry point — runs one agent turn.
```ts
const result = await sdk.ask({
userQuery: "Show my balances on Arbitrum",
metadata: {
accountInfo: [
{ blockchain: 'evm', chain: '42161', user_account: '0xUser' },
],
},
});
console.log(result.finalText);
console.log(result.toolCalls); // structured trace
```
### Streaming with onStep
```ts
const result = await sdk.ask({
userQuery: '...',
metadata: { ... },
onStep: (event) => {
if (event.type === 'tool_call') console.log('calling', event.toolName);
if (event.type === 'text_delta') process.stdout.write(event.text);
},
});
```
## listTools / getTool / executeTool
For when you want to call a tool directly without going through the agent:
```ts
const tools = sdk.listTools();
console.log(tools.map(t => t.name));
const priceTool = sdk.getTool('PriceTool');
const result = await priceTool.execute({
tokenAddresses: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48',
chainId: 1,
});
```
Direct tool calls are faster and cheaper (no LLM round-trip) but require you to know exactly which tool you want.
## Custom system prompt
```ts
const sdk = new DZapSDK({
systemPrompt: `
You are an assistant for DefiDegens, a DeFi research app.
Always check user balances before suggesting trades.
Never execute swaps over $1000 without explicit confirmation.
`,
});
```
The system prompt nudges tool selection and adds guardrails.
## Multi-tenant
Pass `sessionId` to scope memory per user:
```ts
await sdk.ask({ userQuery: '...', sessionId: 'user-42', metadata: { ... } });
```
Memory keyed by `sessionId` lets multi-user apps avoid cross-talk.
## See also
- [ZapBot](/ai/zapbot/overview) — the agent the SDK runs.
- [Tools](/ai/tools/overview) — what the agent can call.
- [Vibe coding](/ai/vibe-coding) — prompt patterns.
# === ai/mcp/overview.mdx ===
---
title: "MCP Server"
description: "Plug DZap into Claude Desktop, Cursor, and any MCP-compatible client."
sidebarTitle: "Overview"
icon: "plug"
---
The DZap MCP server exposes DZap AI capabilities through a **tool-based interface for MCP-compatible clients**. Connect once; the client can discover and call DZap tools through the standard MCP flow.
## What you get
- **Discovery** — clients list available tools and inspect their schemas.
- **Invocation** — clients call tools with structured inputs.
- **Safety** — sensitive actions are clearly marked and gated.
- **Observability** — responses are structured enough for clients to explain what happened.
## When to use it
Connect DZap to an MCP-capable assistant and let it call tools directly.
Curated subset of DZap tools for support, ops, research, or strategy.
MCP as the first integration layer before you decide on a tighter contract.
DZap tools alongside your code editor.
## Tool families
The MCP server exposes tools across several domains:
- Asset and token lookup
- Prices and balances
- Routes and quotes
- DeFi positions and pool context
- Transaction build and simulation
- Docs and knowledge retrieval
- Analytics and sentiment helpers
See [Tool Categories](/ai/tools/overview) for the full breakdown.
## Conceptual request flow
```
User
↓ asks a DeFi question
MCP Client (Claude Desktop / Cursor / your agent)
↓ tools.list / tool call
DZap MCP Server (https://ai.dzap.io/sse)
↓ executes selected tool
DZap Tools
↓ structured result
MCP Client → User
```
## Connection
The DZap MCP server is hosted at **`https://ai.dzap.io/sse`** (Server-Sent Events transport).
Most clients use the `mcp-remote` helper to bridge their config to the remote endpoint:
```json
{
"mcpServers": {
"DZapAI": {
"command": "npx",
"args": [
"mcp-remote",
"https://ai.dzap.io/sse"
]
}
}
}
```
Per-client paths and exact format are in the dedicated pages.
## What's read-only vs execution-sensitive
Tools split into two classes:
| Class | Examples | Confirmation |
|---|---|---|
| **Read** | balances, prices, positions, routes | none |
| **Execution-sensitive** | build, simulate, perform | gated by client + runtime |
For the security model, see [Safety & Execution](/ai/safety-and-execution).
## Next
Connect in 60 seconds.
Integrate into your own agent runtime.
# === ai/mcp/claude-desktop.mdx ===
---
title: "Claude Desktop"
description: "Connect Claude Desktop to the DZap MCP server."
sidebarTitle: "Claude Desktop"
icon: "anthropic"
---
A fast local setup for testing MCP tool exposure, trying DZap AI flows interactively, and validating prompts against real tool responses.
## Setup
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Create the file if it doesn't exist.
```json
{
"mcpServers": {
"DZapAI": {
"command": "npx",
"args": [
"mcp-remote",
"https://ai.dzap.io/sse"
]
}
}
}
```
Fully quit (⌘Q on macOS) and relaunch so the MCP server is discovered.
Try prompts such as:
- `List all tools available from DZapAI.`
- `Show me what DZap tools can inspect balances or prices.`
- `Which tools are useful for route discovery or simulation?`
## Suggested first workflow
Start with read-only flows:
1. List tools.
2. Inspect token or price tooling.
3. Test balance or market queries.
4. Test route discovery.
5. Move to build and simulation only after tool behavior is clear.
## Troubleshooting
- Confirm Claude Desktop loaded the config file.
- Confirm the `mcp-remote` transport helper is reachable.
- Confirm the MCP endpoint URL is correct.
- Inspect the tool schema and arguments.
- Test with a simpler read-only tool first.
- Check whether your environment blocks the remote transport.
- Ask Claude to explain which tool it selected and why.
- Prefer narrower prompts while validating a new setup.
## Good practice
Keep your first examples simple and deterministic. People learn faster from balance checks, token lookup, quote retrieval, and simulation previews than from grand demos that try to reinvent macroeconomics and a trade plan at the same time.
# === ai/mcp/cursor.mdx ===
---
title: "Cursor"
description: "DZap MCP for Cursor IDE."
sidebarTitle: "Cursor"
icon: "code"
---
## Setup
`~/.cursor/mcp.json`
Create it if missing.
```json
{
"mcpServers": {
"DZapAI": {
"command": "npx",
"args": [
"mcp-remote",
"https://ai.dzap.io/sse"
]
}
}
}
```
Cmd-Q and relaunch.
Open Composer (Cmd-I). DZap tools are now available. Try:
> Get the current price of WETH on Base.
## Pair with the DZap Skill
For coding tasks (writing SDK calls, building API clients), pair the MCP server with the `dzap-sdk` Skill. The MCP server gives Cursor real-time data; the Skill gives Cursor the API conventions for code completions.
See [Skills → DZap SDK](/ai/skills/dzap-sdk).
## Per-project config
To restrict DZap MCP to specific projects, place a `.cursor/mcp.json` in the project root instead of the user-level config. The project config takes precedence.
## Troubleshooting
If Cursor doesn't pick up DZap tools, check Cursor's MCP logs (View → Output → MCP). Most issues are reachability problems — confirm the remote endpoint is accessible from your network.
# === ai/mcp/custom-clients.mdx ===
---
title: "Custom Clients"
description: "Connect your own application or agent runtime to DZap AI."
sidebarTitle: "Custom clients"
icon: "plug"
---
Use this path when you want to integrate DZap AI into your own application, orchestration layer, or agent runtime.
## Good fit
Custom clients are a strong choice when you need:
- Tighter control over prompts and tool policy.
- Your own UI or app workflow.
- Internal guardrails around execution.
- App-specific logging, auth, or observability.
## Integration model
```
Your App / Agent
↓
Client Layer (your auth, your logging)
↓
DZap MCP (https://ai.dzap.io/sse) or Tool Gateway
↓
DZap Tooling
↓
Protocol / Execution Services
```
## Recommended approach
### Step 1: Define your tool subset
Most apps should not expose every available capability. Start narrow:
- Asset discovery
- Balances and positions
- Route and quote generation
- Build and simulate
### Step 2: Add role-aware behavior
Different users or agents may need different tool access:
- **Support copilot** — docs + read-only tooling.
- **Analyst agent** — research + market tools.
- **Execution copilot** — build + simulate + explicit approval path.
### Step 3: Keep confirmations explicit
For anything that may lead to execution, the client should make the assistant state:
- What will happen.
- What chain and asset are involved.
- What assumptions were made.
- Whether this is read, build, simulate, or execute.
### Step 4: Log tool usage
At minimum, log:
- Selected tool.
- Normalized inputs.
- Returned outputs.
- Decision step in the conversation.
- Whether the action was gated or confirmed.
## Connecting via the MCP SDK
```ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
const transport = new SSEClientTransport(new URL('https://ai.dzap.io/sse'));
const client = new Client(
{ name: 'my-agent', version: '1.0.0' },
{ capabilities: {} },
);
await client.connect(transport);
// Discover tools
const tools = await client.listTools();
console.log(tools.tools.map(t => t.name));
// Call a tool
const result = await client.callTool({
name: 'PriceTool',
arguments: {
tokenAddresses: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48',
chainId: 1,
},
});
```
## Design tips
### Prefer tool orchestration over free-form prompting
Let the client orchestrate structure. Let the model do interpretation.
### Separate advisory from execution-capable flows
Don't make every agent one prompt away from execution.
### Make failure states readable
Users should understand whether the system failed because of:
- Missing wallet context.
- Unsupported chain or asset.
- Invalid arguments.
- Policy restrictions.
- Transport or service errors.
## See also
- [MCP overview](/ai/mcp/overview)
- [Safety & Execution](/ai/safety-and-execution)
- [SDK-AI](/ai/sdk-ai) — embed-in-app alternative.
# === ai/skills/overview.mdx ===
---
title: "Skills"
description: "Curated context bundles for AI editors — Cursor, Claude Code."
sidebarTitle: "Overview"
icon: "book"
---
A Skill is a markdown bundle that primes an LLM editor with DZap conventions. Once loaded, completions and code generations match real DZap APIs — no more hallucinated endpoints, wrong parameter names, or stale type hints.
## Three published skills
`@dzapio/sdk` — swaps, bridges, zaps, approvals, quotes, build-tx.
REST API for Fuse — quote, build, bundle, execute, status.
REST API for Core swap + bridge.
## What a Skill contains
- **Reference docs** — every endpoint or method, with parameters and response shapes.
- **Code patterns** — common multi-call sequences (quote → approve → execute).
- **Type hints** — TypeScript interfaces / JSON schemas.
- **Example payloads** — real curl + TS code for each operation.
## Skill vs Tool vs MCP
| Layer | Lives in | When | Driven by |
|---|---|---|---|
| **Skill** | Editor (Cursor, Claude Code) | At write-time | Human typing |
| **Tool** | Agent runtime | At runtime | LLM agent |
| **MCP** | Client + server | Either | Either |
Skills are for *coding*. Tools are for *running*. MCP can do both.
## Install
Skills are markdown bundles published to GitHub. Cursor and Claude Code both read them via their skill systems:
```bash
# Cursor
mkdir -p .cursor/rules
cp -r dzap-sdk-skill/* .cursor/rules/
# Claude Code
mkdir -p ~/.claude/skills
ln -s /path/to/dzap-sdk-skill ~/.claude/skills/dzap-sdk
```
Per-skill setup is in the dedicated pages.
## Why ship Skills separately from MCP?
- Skills are **static** — markdown, no process to spawn. Always available.
- MCP is **dynamic** — runs DZap tools live. More powerful, more setup.
- They're complementary — install both for the best experience.
## Authoring your own
Custom Skills (e.g. for your DZap-built product) come soon. See [Authoring](/ai/skills/authoring).
# === ai/skills/dzap-sdk.mdx ===
---
title: "Skill: dzap-sdk"
description: "Prime your editor with @dzapio/sdk conventions."
sidebarTitle: "dzap-sdk"
icon: "js"
---
The `dzap-sdk` Skill teaches your editor (Cursor, Claude Code) about every method on `@dzapio/sdk`. Result: completions match real method signatures and parameter names.
## What it covers
- `DZapClient.getInstance()` initialization patterns
- Trade methods: `getTradeQuotes`, `buildTradeTxn`, `trade`, `tradeGasless`, status
- Zap methods: `getZapQuote`, `buildZapTxn`, `zap`, bundles, status
- Approvals: ERC20, Permit2, EIP-2612, AutoPermit
- Token utilities, chain config, intent signing
## Install
```bash
git clone https://github.com/dzap-io/skills.git
mkdir -p .cursor/rules
cp skills/dzap-sdk/*.md .cursor/rules/
```
Reload Cursor; the Skill is active per-project.
```bash
git clone https://github.com/dzap-io/skills.git
ln -s "$PWD/skills/dzap-sdk" ~/.claude/skills/dzap-sdk
```
Use via `/dzap-sdk` or let Claude auto-pick when relevant.
## What you'll notice
Without the Skill, an LLM might write:
```ts
// hallucinated — wrong method name, wrong params
const quote = await dzap.getQuote({ from: '...', to: '...' });
```
With the Skill:
```ts
const quote = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xUser',
data: [{ srcToken: '...', destToken: '...', amount: '1000000', slippage: 1 }],
});
```
## Pair with MCP
For runtime calls (real prices, real balances), add the [DZap MCP server](/ai/mcp/overview) to the same editor. Skill primes code generation; MCP fetches live data.
# === ai/skills/dzap-fuse-api.mdx ===
---
title: "Skill: dzap-fuse-api"
description: "REST API conventions for Fuse — quote, build, bundle, execute."
sidebarTitle: "dzap-fuse-api"
icon: "bolt"
---
The `dzap-fuse-api` Skill primes your editor with the Fuse REST surface (`zap.dzap.io`). Every endpoint, every parameter, every response shape.
The Skill keeps the legacy "Zap" name in code; documentation publishes as **Fuse**.
## What it covers
- `POST /v1/quote` — request shape + ranked-route response
- `POST /v1/buildTx` — calldata generation
- `POST /v1/bundle` — multi-step intents
- `POST /v1/execute` — gasless intent submission
- `GET /v1/status` — single + batch tracking
- Pools, user, tokens, config endpoints
## Install
```bash
git clone https://github.com/dzap-io/skills.git
cp skills/dzap-zap-api/*.md .cursor/rules/
```
```bash
ln -s "$PWD/skills/dzap-zap-api" ~/.claude/skills/dzap-fuse-api
```
## Use cases
- Building a backend service that orchestrates Fuse intents.
- Wiring up a frontend that calls `/v1/quote` and renders the path.
- Writing test fixtures with real-shape responses.
## Pair with the API reference
Read [Fuse API → Quote](/api/fuse/quote) alongside the Skill. The Skill teaches the LLM; the API reference teaches you.
# === ai/skills/dzap-trade-api.mdx ===
---
title: "Skill: dzap-trade-api"
description: "REST API conventions for Trade — swap, bridge, DCA, tokens."
sidebarTitle: "dzap-trade-api"
icon: "arrows-rotate"
---
The `dzap-trade-api` Skill covers the Trade REST surface (`api.dzap.io`) — swaps, bridges, DCA, tokens, and webhooks.
## What it covers
- `POST /v1/swap`, `/v1/bridge` — execution endpoints
- `POST /v1/quotes` — best-route quotes
- `POST /v1/buildTx` — calldata
- `POST /v1/gasless` — gasless variant
- DCA endpoints
- Token endpoints (details, balances, prices, historical)
- Webhook payloads + verification
## Install
```bash
git clone https://github.com/dzap-io/skills.git
cp skills/dzap-trade-api/*.md .cursor/rules/
```
```bash
ln -s "$PWD/skills/dzap-trade-api" ~/.claude/skills/dzap-trade-api
```
## Use cases
- Building DCA workflows.
- Integrating webhook listeners.
- Writing custom rate-limited backends in front of DZap.
## Pair with the API reference
The Skill primes; [API → Trade](/api/trade/overview) documents authoritatively.
# === ai/skills/authoring.mdx ===
---
title: "Authoring Skills"
description: "Build and publish a custom DZap Skill."
sidebarTitle: "Authoring"
icon: "pen"
---
## What's coming
The DZap Skills authoring guide will cover:
- The Skill file format (frontmatter + markdown sections).
- Patterns for endpoint catalogs, type hints, and example payloads.
- Publishing to the official skills registry.
- Versioning a Skill alongside the surface it documents.
## In the meantime
If you want to write a Skill today, the three published skills (`dzap-sdk`, `dzap-fuse-api`, `dzap-trade-api`) are open-source. Fork their structure:
```bash
git clone https://github.com/dzap-io/skills.git
```
Each skill is just a folder of markdown files with a clear naming scheme. Mirror that for your own surface.
## Stay in the loop
Watch the [changelog](/resources/changelog) or `@dzap_io` on X for the authoring-guide release.
# === ai/tools/overview.mdx ===
---
title: "Tool Categories"
description: "How DZap AI tools are organized — and what's read-only vs execution-sensitive."
sidebarTitle: "Overview"
icon: "wrench"
---
DZap AI works best when tools are presented in clear domains rather than as one giant bucket of magical functions.
## The five categories
### 1. Asset and market tools
Identify assets and fetch market context.
Typical examples: token lookup, token metadata, token price, amount conversion, chain or network context, trending tokens, news and sentiment.
→ See [Market Data](/ai/tools/market-data) for the concrete tools we ship.
### 2. Wallet and portfolio tools
Inspect what a wallet currently holds or is doing.
Typical examples: wallet balances, position lookup, portfolio summary, transaction history, health and risk indicators, watchlists and alerts.
→ See [Wallet & DeFi](/ai/tools/wallet-defi).
### 3. Routing and execution tools
Move from idea to executable plan.
Typical examples: swap quote, bridge quote, pool or vault details, build transaction, simulate transaction, perform transaction, gas estimate.
→ See [Wallet & DeFi](/ai/tools/wallet-defi) (`ZapCallDataGeneratorTool`, `PerformZapTool`).
### 4. Safety and policy tools
Validate actions before anything touches real execution.
Typical examples: token verification, approval checks, allowance checks, route sanity validation, slippage policy checks, execution risk evaluation.
→ Surfaces today through SDK approval modes; richer policy tools land with the runtime layer ([roadmap](/ai/agent-integration)).
### 5. Knowledge and support tools
Help assistants answer integration or product questions.
Typical examples: docs retrieval, RAG over documentation, integration guidance, troubleshooting support.
→ See [Data Sources](/ai/tools/data-sources) (`RagOverDocsTool`, `WebSearchTool`).
## How tools work
Each tool has:
- **Name** — identifier the agent uses to call it.
- **Description** — natural-language hint for the model.
- **Parameters** — typed schema.
- **execute** — async function that does the work.
When ZapBot decides to call a tool, the model emits structured arguments matching the schema; the runtime validates, calls `execute`, and feeds results back.
## Read vs execution-sensitive
| Read | Execution-sensitive |
|---|---|
| `PriceTool`, `BalanceTool`, `PoolTool`, `WebSearchTool`, ... | `PerformZapTool`, `ZapCallDataGeneratorTool`, `ChangeChainTool` |
| Always safe | Confirmation required |
| Cached where possible | Idempotent on retry; no double-execution |
For the safety model, see [Safety & Execution](/ai/safety-and-execution).
## Suggested maturity model
| Category | Best first step | Later expansion |
|---|---|---|
| Asset & market | price, token lookup | news, sentiment, analytics |
| Wallet & portfolio | balances, positions | alerts, history, health monitoring |
| Routing & execution | quotes, build, simulate | policy-aware execute |
| Safety & policy | slippage, validation | approval and risk engines |
| Knowledge | docs search | product copilots and support agents |
## Calling tools directly
You don't have to go through the agent. From SDK-AI:
```ts
const priceTool = sdk.getTool('PriceTool');
const result = await priceTool.execute({
tokenAddresses: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48',
chainId: 1,
});
```
Direct calls skip the LLM — faster, cheaper, deterministic.
## Concrete tool inventory
Tools shipped today (from `ToolNames.ts`):
- `PriceTool`, `BalanceTool`, `TokenAddressTool`, `DollarToTokenAmountTool`
- `TrendingNewsTool`, `TrendingTokenTool`, `SentimentTool`, `PricePredictionTool`
- `ZapCallDataGeneratorTool`, `BridgeLinkGeneratorTool`, `SwapLinkGeneratorTool`
- `WebSearchTool`, `DefiPositionsTool`, `RagOverDocsTool`, `PoolTool`
- `RequestChainChangeTool`, `ChangeChainTool`, `ShowBalanceUITool`
- `SheluderTool`, `GetAllSchedulesTool`, `PerformZapTool`
For per-tool parameters and examples, see the four detail pages:
Balances, pools, positions, zap execution.
Prices, predictions, sentiment, trending.
Web search, RAG, external APIs.
Link generators, scheduler, chain change.
# === ai/tools/wallet-defi.mdx ===
---
title: "Wallet & DeFi Tools"
description: "Balances, pools, positions, zap execution."
sidebarTitle: "Wallet & DeFi"
icon: "wallet"
---
Tools that read and write user state across chains.
## BalanceTool
Returns native + ERC20 balances for an account on a chain.
```ts
const result = await sdk.getTool('BalanceTool').execute({
account: '0xUser',
chainId: 1,
});
// → array of { address, symbol, balance, decimals, valueUSD }
```
| Param | Type | Required |
|---|---|---|
| `account` | string | yes |
| `chainId` | number | yes |
| `tokens` | string[] | no — defaults to all |
## DefiPositionsTool
Returns LP / staking / vault positions for an account.
```ts
const positions = await sdk.getTool('DefiPositionsTool').execute({
account: '0xUser',
chainId: 8453,
});
```
Use it for portfolio summaries: "What positions do I have on Base?"
## PoolTool
Lists pools by chain, protocol, or token pair. Used by the agent for "best pool" queries.
```ts
const pools = await sdk.getTool('PoolTool').execute({
chainId: 8453,
protocol: 'uniswap-v3', // optional
tokens: ['0x8335...', '0x4200...'], // optional
limit: 10,
});
```
## ZapCallDataGeneratorTool
Builds the calldata for a Fuse zap (without executing). The agent uses this to surface a plan before asking for confirmation.
```ts
const tx = await sdk.getTool('ZapCallDataGeneratorTool').execute({
srcChainId: 8453,
destChainId: 8453,
srcToken: '0x8335...',
destToken: '0xPool...',
amount: '100000000',
account: '0xUser',
recipient: '0xUser',
refundee: '0xUser',
slippage: 1,
});
```
## PerformZapTool
Executes a zap end-to-end — signs and sends. Write tool: requires confirmation.
```ts
const result = await sdk.getTool('PerformZapTool').execute({
/* same params as ZapCallDataGeneratorTool */
privateKey: process.env.SESSION_KEY, // session-scoped, see Safety
});
```
`PerformZapTool` requires a session-scoped key in process memory. Never pass a long-lived hot wallet key. See [ZapBot Safety](/ai/zapbot/safety).
## ChangeChainTool
Changes the active chain in the agent's context (e.g. "switch to Base"). Affects subsequent tool calls.
## RequestChainChangeTool
Asks the connected wallet client to change networks. Useful when the agent detects a chain mismatch.
## ShowBalanceUITool
Renders a structured balance view for clients that support rich UI cards (e.g. some MCP clients).
# === ai/tools/market-data.mdx ===
---
title: "Market Data Tools"
description: "Prices, predictions, sentiment, trending."
sidebarTitle: "Market data"
icon: "chart-line"
---
Tools that fetch market data from DZap and external sources.
## PriceTool
Fetch USD price for one or more tokens.
```ts
const result = await sdk.getTool('PriceTool').execute({
tokenAddresses: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48,0xC02aaa39b223FE8D0A0e5C4F27eAD9083C756Cc2',
chainId: 1,
});
// → { '0xA0b...': '1.00', '0xC02...': '3450.12' }
```
| Param | Type | Required |
|---|---|---|
| `tokenAddresses` | string (comma-separated) | yes |
| `chainId` | number | yes |
## PricePredictionTool
Forecasts short-horizon price movement using ensemble signals (Allora, internal models).
```ts
const prediction = await sdk.getTool('PricePredictionTool').execute({
symbol: 'ETH',
horizon: '1h',
});
// → { direction: 'up' | 'down', confidence: 0..1, expectedRange: [...] }
```
Predictions are not financial advice. Use as a signal, not a decision.
## TrendingTokenTool
Returns trending tokens across DZap volume, social signals, and aggregator data.
```ts
const trending = await sdk.getTool('TrendingTokenTool').execute({
chainId: 8453,
timeframe: '24h', // 1h | 24h | 7d
limit: 10,
});
```
## TrendingNewsTool
Fetches recent crypto news, optionally scoped to a token.
```ts
const news = await sdk.getTool('TrendingNewsTool').execute({
symbol: 'ETH', // optional
limit: 10,
});
```
Backed by CryptoPanic. Requires `CRYPTOPANIC_API_KEY`.
## SentimentTool
Aggregates sentiment from social and news for a token.
```ts
const sentiment = await sdk.getTool('SentimentTool').execute({
symbol: 'PEPE',
});
// → { score: -1..1, label: 'positive' | 'neutral' | 'negative', sources: [...] }
```
## TokenAddressTool
Resolves token symbols to addresses on a given chain. Useful when the user says "USDC" without specifying which.
```ts
const address = await sdk.getTool('TokenAddressTool').execute({
symbol: 'USDC',
chainId: 42161,
});
// → '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
```
## DollarToTokenAmountTool
Converts a USD amount to wei amount of a token at current prices. Great for "swap $100 of ETH" prompts.
```ts
const wei = await sdk.getTool('DollarToTokenAmountTool').execute({
usdAmount: 100,
tokenAddress: '0xC02...',
chainId: 1,
});
// → '28985507246376811' (USD 100 / 3450 = 0.029 ETH)
```
# === ai/tools/data-sources.mdx ===
---
title: "Data Source Tools"
description: "Web search, RAG, Moralis, Coinstats, Allora, Tavily."
sidebarTitle: "Data sources"
icon: "database"
---
Tools that bring external data to the agent. Most need their own API key (free tiers available).
## WebSearchTool
Live web search for recent news, articles, and protocol updates. Backed by Tavily.
```ts
const results = await sdk.getTool('WebSearchTool').execute({
query: "Recent updates to Aave V3 risk parameters",
limit: 5,
});
```
Requires `TAVILY_API_KEY`.
## RagOverDocsTool
Retrieval over indexed docs — DZap's own documentation corpus plus protocol whitepapers. Useful when the user asks conceptual questions ("how does Permit2 work?").
```ts
const passages = await sdk.getTool('RagOverDocsTool').execute({
query: "How does the Across bridge handle relayer failures?",
limit: 5,
});
// → array of { passage, source, score }
```
Built on BM25 over a corpus indexed at SDK init (`initializeRetrieval: true`).
## Moralis (under data sources)
For deep on-chain data — NFT metadata, transaction history, contract events. Wrapped where useful.
Requires `MORALIS_API_KEY`.
## Coinstats
Historical prices, market cap rankings, gainers/losers. Backed by Coinstats.
Requires `COINSTATS_API_KEY`.
## Allora
Decentralized prediction market data. Used by `PricePredictionTool` underneath.
## Tavily
The default web search backend (used by `WebSearchTool`).
## When agent picks which
The agent prefers DZap-native sources first (PriceTool, PoolTool) and falls back to external sources when:
- Data is not on-chain (news, sentiment).
- Token is unknown to DZap (long-tail).
- User explicitly asks ("search the web").
## Cost notes
| Tool | Cost |
|---|---|
| `WebSearchTool` (Tavily) | Free tier: ~1k req/month |
| `MoralisTool` | Free tier: 25k req/month |
| `Coinstats` | Free tier: 10k req/month |
| `RagOverDocsTool` | Free (local) |
For production, get paid tiers and surface usage to your users where appropriate.
# === ai/tools/utilities.mdx ===
---
title: "Utility Tools"
description: "Link generators, scheduler, ad-hoc helpers."
sidebarTitle: "Utilities"
icon: "screwdriver-wrench"
---
Tools that don't fit cleanly into wallet/market/data categories.
## SwapLinkGeneratorTool
Generates a deep link to the DZap app pre-filling a swap. Useful when the agent suggests a trade but you want the user to execute via the UI.
```ts
const url = await sdk.getTool('SwapLinkGeneratorTool').execute({
fromChain: 42161,
srcToken: '0xaf88...',
destToken: '0x82aF...',
amount: '1000000',
});
// → 'https://app.dzap.io/swap?...'
```
## BridgeLinkGeneratorTool
Same idea, for cross-chain.
```ts
const url = await sdk.getTool('BridgeLinkGeneratorTool').execute({
fromChain: 42161,
toChain: 8453,
srcToken: '0xaf88...',
destToken: '0x8335...',
amount: '10000000',
});
```
## SheluderTool
Schedules a recurring task (DCA, periodic balance check, news poll). Backed by SQLite at `~/.dzapai/schedules.db`.
```ts
await sdk.getTool('SheluderTool').execute({
name: 'Weekly DCA',
cron: '0 9 * * MON', // crontab format
query: 'Swap $100 USDC to ETH on Arbitrum',
account: '0xUser',
});
```
The scheduler runs in-process when the CLI/SDK is alive. For long-running, use a server-side host.
## GetAllSchedulesTool
Lists all scheduled tasks for an account.
```ts
const schedules = await sdk.getTool('GetAllSchedulesTool').execute({
account: '0xUser',
});
```
## RequestChainChangeTool
Signals to the wallet client that the active chain should change. The agent uses this before tools that require a specific chain.
```ts
await sdk.getTool('RequestChainChangeTool').execute({
chainId: 42161,
});
```
## ChangeChainTool
Updates the agent's *internal* notion of the current chain (without touching the wallet). Used in pure-read contexts.
## When to use directly
Most utility tools are agent-driven. Two exceptions where direct calls win:
- **Link generators** in customer-support contexts ("here's a pre-filled link for the user").
- **Scheduler** when you're building a UI that lets users browse and edit their own schedules.
# === ai/plugins/overview.mdx ===
---
title: "Plugins"
description: "Extend DZap AI with custom tools and integrations."
sidebarTitle: "Overview"
icon: "puzzle-piece"
---
## What's planned
A plugin system that lets you:
- **Register custom tools** — your own functions callable by ZapBot.
- **Bind third-party data sources** — bring your own API and have the agent use it.
- **Package + share plugins** — publish to a registry; install with one command.
## In the meantime
Two paths get most of the way there:
### 1. Direct tool registration via SDK-AI
If you embed the agent in your app, you can extend the runtime with your own tool definitions. The pattern follows the Vercel AI SDK tool API. See `ToolFactory.ts` in `DZapAI` for the contract.
### 2. MCP-side extension
If you connect via [MCP](/ai/mcp/overview), add additional MCP servers to your client config. Tools from any connected server are visible to the agent.
```json
{
"mcpServers": {
"dzap": { "command": "npx", "args": ["-y", "dzapai", "mcp"] },
"my-custom": { "command": "node", "args": ["./my-mcp-server.js"] }
}
}
```
This isn't quite a plugin system — closer to "side-load whatever you want into the same client" — but it covers most extension cases until plugins ship.
## Track progress
Watch the [changelog](/resources/changelog) or `@dzap_io` on X.
# === api/introduction.mdx ===
---
title: "API Introduction"
description: "Two surfaces, one router. Fuse API and Trade API."
sidebarTitle: "Introduction"
icon: "code"
---
DZap exposes two HTTP surfaces:
| API | Base URL | Auth | Use for |
|---|---|---|---|
| **Fuse API** | `https://zap.dzap.io` | None (per-IP rate limits) | Intent execution, bundles, gasless |
| **Trade API** | `https://api.dzap.io` | Optional API key | Swaps, bridges, DCA, tokens, status |
Both speak JSON over HTTPS. Both run on the same routing engine.
## Pick one
OpenAPI-backed. Quote, build, bundle, execute, status.
REST routes for the full Core surface plus DCA and webhooks.
## Conventions
- **Amounts are strings in wei** — `"1000000"` is 1 USDC (6 decimals), not `1`.
- **Native tokens** use the sentinel `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. Never the zero address.
- **Slippage is percent** — `1` = 1%, `0.5` = 0.5%.
- **Errors** follow `{ "status": "error", "code": "...", "message": "..." }`. See [Error Codes](/api/error-codes).
## Status & rate limits
| Aspect | Fuse API | Trade API |
|---|---|---|
| Health endpoint | `GET /v1/status` | `GET /v1/status` |
| Default rate limit | 3 req/sec on quote/buildTx | Per-key (or per-IP fallback) |
| Auth | None | Bearer-style API key (optional) |
| Response time SLA | Typical: <200ms quote, <500ms build | Typical: <300ms quote |
See [Authentication](/api/authentication) and [Rate Limits](/api/rate-limits).
## Versioning
All endpoints are under `/v1`. Breaking changes ship under `/v2`; `/v1` stays available with at least 90 days notice. Watch the [changelog](/resources/changelog).
# === api/authentication.mdx ===
---
title: "Authentication"
description: "API keys, IP-based limits, and when each applies."
sidebarTitle: "Authentication"
icon: "key"
---
## TL;DR
- **Fuse API** (`zap.dzap.io`) — no auth. Per-IP rate-limited.
- **Trade API** (`api.dzap.io`) — optional API key. Per-key rate-limited (falls back to per-IP for unauthenticated requests).
## Getting a Trade API key
API keys are issued by DZap to partners. Reach out via [Discord](https://discord.com/invite/aRHESJB9md) or `support@dzap.io` with:
- Your project name
- Expected request volume (req/min)
- Endpoints you'll use most
You'll receive a key tied to your project. Treat it like a password.
## Using a Trade API key
```bash
curl -X POST https://api.dzap.io/v1/quotes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer dzap_xxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{ ... }'
```
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance('dzap_xxxxxxxxxxxxxxxxxxxxxxxx');
```
Never put API keys in client-side code. Proxy through your backend. Server-only.
## What an API key gives you
- **Higher rate limits** — defaults plus per-key tiers.
- **Per-route configuration** — block specific routes, raise limits on others.
- **Usage analytics** — request counts, latency p50/p95, error rates.
## Without a key
You can still call every Trade API endpoint that doesn't gate on auth — quotes, status, tokens, chains. Per-IP rate limits apply (typically 60 req/min, route-specific). Bursts return `429 Too Many Requests`.
## Key rotation
Keys can be rotated on request. The old key remains active for 24 hours after a new one is issued, so you have a rollover window.
# === api/rate-limits.mdx ===
---
title: "Rate Limits"
description: "Per-IP and per-API-key limits, with handling guidance."
sidebarTitle: "Rate limits"
icon: "gauge"
---
DZap rate-limits requests to keep the API responsive for everyone. Limits differ by API and authentication state.
## Limits at a glance
| Surface | Default | With API key |
|---|---|---|
| Fuse API — `/v1/quote` | 3 req/sec/IP | n/a (no auth) |
| Fuse API — `/v1/buildTx` | 3 req/sec/IP | n/a |
| Fuse API — other reads | 60 req/min/IP | n/a |
| Trade API — quotes/build | 60 req/min/IP | per-key tier (typically 5–50 req/sec) |
| Trade API — reads | 120 req/min/IP | per-key tier |
## Response headers
Every response includes:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1714117200
```
`X-RateLimit-Reset` is a Unix timestamp.
## When you hit a limit
You'll get `429 Too Many Requests`:
```json
{
"status": "error",
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 12s.",
"retryAfter": 12
}
```
Retry with exponential backoff. Don't hammer.
## Best practices
- **Cache quotes briefly** — quotes are valid for ~30s; cache server-side if you re-render the same pair.
- **Batch where possible** — `/v1/quotes` accepts an array of items in `data`. One request, many quotes.
- **Use the SDK** — it implements retries with backoff for you.
- **Use an API key for production** — per-key limits are higher and more predictable than per-IP.
## Need more headroom?
Email `support@dzap.io` with your projected req/sec and use case. Higher tiers are available for production deployments.
# === api/error-codes.mdx ===
---
title: "Error Codes"
description: "Errors you'll see, what they mean, and how to recover."
sidebarTitle: "Error codes"
icon: "circle-exclamation"
---
All API errors share one shape:
```json
{
"status": "error",
"code": "ERROR_CODE",
"message": "Human-readable explanation",
"details": { ... }
}
```
## Top-level codes
| Code | HTTP | What it means | Recovery |
|---|---|---|---|
| `BAD_REQUEST` | 400 | Validation failed (missing/invalid field) | Check `details` for field-level errors |
| `UNAUTHORIZED` | 401 | API key missing or invalid | Re-issue key; check header format |
| `FORBIDDEN` | 403 | Endpoint blocked for this key | Check route permissions |
| `NOT_FOUND` | 404 | Resource (chain, token, txId) doesn't exist | Verify inputs |
| `RATE_LIMITED` | 429 | Per-IP or per-key cap hit | Backoff; honor `retryAfter` |
| `INTERNAL_SERVER_ERROR` | 500 | Routing/upstream failure | Retry; if persistent, contact support |
| `BAD_GATEWAY` | 502 | Upstream protocol unavailable | Retry; route may be temporarily un-quotable |
## Routing-specific codes
| Code | Meaning |
|---|---|
| `NO_ROUTE_FOUND` | No DEX/bridge can route this pair at this size |
| `INSUFFICIENT_LIQUIDITY` | Route exists but liquidity is too thin |
| `SLIPPAGE_TOO_TIGHT` | Estimated output below `minReturn`; loosen slippage |
| `AMOUNT_TOO_SMALL` | Below provider minimum (often $1 equivalent) |
| `AMOUNT_TOO_LARGE` | Above provider maximum (route-specific) |
| `UNSUPPORTED_TOKEN` | Token not in any supported pool |
| `UNSUPPORTED_CHAIN` | Chain not in supported set |
| `UNSUPPORTED_PAIR` | Tokens supported individually but not as a pair |
## Contract-revert errors
When the on-chain transaction reverts, DZap surfaces a structured `ContractErrorResponse`:
```json
{
"status": "error",
"code": "CONTRACT_REVERT",
"message": "Slippage exceeded",
"details": {
"action": "swap",
"provider": "paraswap",
"reason": "minOut not met",
"txHash": "0x..."
}
}
```
`details.action` is the failing leg of a multi-step bundle. Useful for surfacing UI hints (e.g. "swap leg 2 reverted").
## Programmatic handling
```ts
try {
const quotes = await dzap.getTradeQuotes({ ... });
} catch (e: any) {
if (e.code === 'NO_ROUTE_FOUND') {
// suggest different tokens/amounts
} else if (e.code === 'RATE_LIMITED') {
await sleep(e.retryAfter * 1000);
return retry();
} else {
throw e;
}
}
```
The SDK normalizes errors to `{ code, message, details }` regardless of upstream source.
# === api/fuse/quote.mdx ===
---
title: "Get Quote"
description: "Quote a Fuse intent — same-chain or cross-chain, swap or zap."
sidebarTitle: "Quote"
api: "POST https://zap.dzap.io/v1/quote"
---
Returns the best path for the requested operation, including approval data, expected output, and per-step fees.
### Body
Source token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native.
Source chain ID.
Destination token (or LP/NFT) address.
Destination chain ID. Same as `srcChainId` for same-chain.
Amount to swap or liquidity to add (in wei). Optional for some operations.
Recipient address for the resulting tokens / position.
Slippage tolerance, in percent. `0.5` = 0.5%.
Account initiating the zap.
Encoded Permit2 data for ERC20 tokens (optional).
NFT-related operation details (e.g. Uniswap V3 LP NFT).
NFT ID associated with the zap.
Pool-specific details for liquidity operations.
Lower tick (concentrated liquidity).
Upper tick.
Whitelist of bridges to consider.
Whitelist of swap protocols to consider.
### Response
`"success"` on 200.
Estimated output amount (in destination token wei).
Approval to grant before executing.
Spender address.
Token contract to call.
Amount to approve.
Ordered list of steps. Each step: `action`, `protocol`, `input[]`, `output[]`, `fee[]`, `estimatedDuration`.
### Examples
```bash curl
curl -X POST https://zap.dzap.io/v1/quote \
-H "Content-Type: application/json" \
-d '{
"srcToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"srcChainId": 8453,
"destToken": "0xd0b53D9277642d899DF5C87A3966A349A798F224",
"destChainId": 8453,
"amount": "5000000",
"recipient": "0x99BCEBf44433E901597D9fCb16E799a4847519f6",
"slippage": 0.5,
"account": "0x99BCEBf44433E901597D9fCb16E799a4847519f6"
}'
```
```ts SDK
const quote = await dzap.getZapQuote({
srcToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
srcChainId: 8453,
destToken: '0xd0b53D9277642d899DF5C87A3966A349A798F224',
destChainId: 8453,
amount: '5000000',
recipient: '0x99BC...',
slippage: 0.5,
account: '0x99BC...',
});
```
```json 200
{
"status": "success",
"data": {
"amountOut": "918943376897193",
"approvalData": {
"callTo": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"approveTo": "0x1d46863e3592745008b5CbbAC12014F67329A9b8",
"amount": "1680715"
},
"path": [
{
"action": "swap",
"protocol": { "id": "dzap", "name": "Dzap Aggregator" },
"input": [{ "amount": "1680715", "asset": { "symbol": "USDC", "chainId": 8453 } }],
"output": [{ "amount": "918943376897193", "minReturn": "918024433520296", "asset": { "symbol": "WETH" } }],
"estimatedDuration": 10
}
]
}
}
```
# === api/fuse/build-tx.mdx ===
---
title: "Build Transaction"
description: "Compile a Fuse intent into ready-to-sign transaction calldata."
sidebarTitle: "Build Tx"
api: "POST https://zap.dzap.io/v1/buildTx"
---
Takes a quote (or the same params you passed to `/v1/quote`) and returns transaction data ready to sign and submit.
### Body
Amount in wei.
Address to refund if cross-chain settlement fails.
Permit2 / EIP-2612 signature payload, if you signed one.
### Response
Contract to call.
Hex-encoded calldata.
Native value to send (for native-token swaps).
Suggested gas limit.
Bind for status polling.
### Examples
```bash curl
curl -X POST https://zap.dzap.io/v1/buildTx \
-H "Content-Type: application/json" \
-d '{ "srcToken": "...", "srcChainId": 8453, ... }'
```
```ts SDK
const tx = await dzap.buildZapTxn({
srcToken: '0x...',
srcChainId: 8453,
destToken: '0x...',
destChainId: 8453,
amount: '5000000',
recipient: '0x...',
refundee: '0x...',
slippage: 0.5,
account: '0x...',
});
// Sign + send via your wallet client
```
```json 200
{
"status": "success",
"data": {
"to": "0x1d46863e3592745008b5CbbAC12014F67329A9b8",
"data": "0x...",
"value": "0",
"gasLimit": "350000",
"txId": "0xabc..."
}
}
```
Use the `txId` to poll `/v1/status` until the (possibly cross-chain) settlement completes.
# === api/fuse/status.mdx ===
---
title: "Status"
description: "Track a Fuse intent — single or batch."
sidebarTitle: "Status"
api: "GET https://zap.dzap.io/v1/status"
---
Returns step-level status for one or many intents. Cross-chain intents are async; poll until `completed`.
### Query
Single intent ID (returned from `/v1/buildTx`).
Comma-separated `srcChainId-txHash` pairs, e.g. `8453-0xabc,42161-0xdef`.
Source transaction hash. Requires `chainId`.
Source chain ID for `txHash`.
### Response
One of `pending`, `completed`, `failed`, `refunded`.
Per-leg detail: protocol, status, txHash, timestamps.
Final received amount + asset, when `completed`.
### Examples
```bash curl
curl "https://zap.dzap.io/v1/status?txIds=8453-0xabc...,42161-0xdef..."
```
```ts SDK
const status = await dzap.getZapTxnStatus({
txId: '0xabc...',
});
```
```json 200
{
"status": "completed",
"steps": [
{ "action": "swap", "protocol": "paraswap", "status": "completed", "txHash": "0xabc..." },
{ "action": "bridge", "protocol": "across", "status": "completed", "txHash": "0xdef..." }
],
"output": { "amount": "918943376897193", "asset": { "symbol": "WETH" } }
}
```
# === api/fuse/bundle.mdx ===
---
title: "Bundle"
description: "Compose multi-step intents — swap + bridge + LP-deposit, etc."
sidebarTitle: "Bundle"
api: "POST https://zap.dzap.io/v1/bundle"
---
Submit a multi-step intent that settles as one signature. Solvers pick up the bundle and execute end-to-end.
### Body
User account.
Ordered list of bundle steps. See "Step shape" below.
EIP-712 signature for gasless settlement (optional).
Intent body, when submitting a signed intent.
Default 1%.
#### Step shape
Each entry in `steps[]`:
One of `swap`, `bridge`, `zap`.
Required for `bridge` and cross-chain `zap`.
In wei. Inferred from the previous step's output if omitted.
For `zap`: `add-liquidity`, `remove-liquidity`, `deposit`, `mint`.
Pool address (for liquidity / deposit actions).
### Response
Use to poll `/v1/status`.
Resolved per-step plan with selected protocols.
### Examples
```bash curl
curl -X POST https://zap.dzap.io/v1/bundle \
-H "Content-Type: application/json" \
-d '{
"account": "0xUser",
"steps": [
{ "type": "bridge", "srcChainId": 42161, "destChainId": 8453, "srcToken": "0xaf88...", "destToken": "0x8335...", "amount": "100000000" },
{ "type": "zap", "srcChainId": 8453, "destChainId": 8453, "srcToken": "0x8335...", "destToken": "0xPool...", "action": "add-liquidity", "pool": "0xPool..." }
],
"slippage": 0.5
}'
```
```ts SDK
const bundle = await dzap.getZapBundleQuote({
account: '0xUser',
steps: [/* ... */],
});
```
```json 200
{
"status": "success",
"data": {
"bundleId": "0xabc123...",
"steps": [
{ "type": "bridge", "protocol": "across", "estimatedDuration": 90 },
{ "type": "zap", "protocol": "uniswap-v3", "estimatedDuration": 10 }
]
}
}
```
# === api/fuse/execute.mdx ===
---
title: "Execute"
description: "Submit a signed gasless intent for solver settlement."
sidebarTitle: "Execute"
api: "POST https://zap.dzap.io/v1/execute"
---
Submits a signed EIP-712 intent. The solver network picks it up and settles. Used in the gasless flow.
### Body
The full intent body returned from `/v1/quote` (must include `txId`, `nonce`, `deadline`, `executorFeesHash`, `swapDataHash`).
EIP-712 signature over the intent.
One of `swap`, `bridge`, `swapBridge`.
### Response
Use to poll `/v1/status`.
Unix timestamp the relay accepted the intent.
### Examples
```bash curl
curl -X POST https://zap.dzap.io/v1/execute \
-H "Content-Type: application/json" \
-d '{
"intent": { "txId": "0x...", "nonce": "1", "deadline": 1714200000, "executorFeesHash": "0x...", "swapDataHash": "0x..." },
"signature": "0x...",
"txType": "swapBridge"
}'
```
```ts SDK
import { signGaslessDzapUserIntent } from '@dzapio/sdk';
const signature = await signGaslessDzapUserIntent({ /* ... */ });
await fetch('https://zap.dzap.io/v1/execute', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ intent: quote, signature, txType: 'swapBridge' }),
});
```
```json 200
{
"status": "success",
"data": { "txId": "0xabc...", "acceptedAt": 1714117200 }
}
```
See [Gasless](/products/dzap-fuse/gasless) for the full signing flow.
# === api/fuse/pools.mdx ===
---
title: "Pools"
description: "List pools and fetch pool metadata."
sidebarTitle: "Pools"
---
## List pools
```
GET https://zap.dzap.io/v1/pools
```
Returns pools available across supported protocols, optionally filtered by chain or DEX.
### Query
Filter by chain.
e.g. `uniswap-v3`, `pancake-v3`, `aerodrome`.
Comma-separated token addresses; returns pools containing all listed tokens.
Default 50, max 200.
### Response
List of pools with `address`, `protocol`, `tokens`, `tvl`, `apr`, `feeTier`.
## Pool details
```
POST https://zap.dzap.io/v1/pool/details
```
### Body
### Response
Full pool detail: tokens, tick range, current tick, liquidity, recent trades.
### Examples
```bash list
curl "https://zap.dzap.io/v1/pools?chainId=8453&protocol=uniswap-v3&limit=10"
```
```bash details
curl -X POST https://zap.dzap.io/v1/pool/details \
-H "Content-Type: application/json" \
-d '{ "chainId": 8453, "poolAddress": "0xd0b53D9277642d899DF5C87A3966A349A798F224" }'
```
# === api/fuse/user.mdx ===
---
title: "User Endpoints"
description: "Positions, balances, and transaction history."
sidebarTitle: "User"
---
## Positions
```
GET https://zap.dzap.io/v1/user/positions?account=0x...&chainId=8453
```
Returns LP / staking / vault positions held by `account`.
Positions with `protocol`, `pool`, `tokens`, `value`, `pnl`.
## Balances
```
GET https://zap.dzap.io/v1/user/balances?account=0x...&chainId=8453
```
Returns ERC20 balances + native, with USD valuation.
Tokens with `address`, `symbol`, `balance`, `valueUSD`.
## Transactions
```
GET https://zap.dzap.io/v1/user/transactions?account=0x...&limit=20
```
Returns recent DZap transactions for `account`.
Transactions with `txHash`, `chainId`, `action`, `status`, `timestamp`, `tokens`.
### Examples
```bash positions
curl "https://zap.dzap.io/v1/user/positions?account=0x99BCEBf44433E901597D9fCb16E799a4847519f6"
```
```bash balances
curl "https://zap.dzap.io/v1/user/balances?account=0x99BC...&chainId=8453"
```
```bash transactions
curl "https://zap.dzap.io/v1/user/transactions?account=0x99BC...&limit=20"
```
# === api/fuse/tokens.mdx ===
---
title: "Tokens"
description: "Token details, prices, and balances."
sidebarTitle: "Tokens"
---
Token reads share the `/v1/token/*` namespace.
## Token details
```
POST https://zap.dzap.io/v1/token/details
```
Include holder balance if set.
`address`, `symbol`, `name`, `decimals`, `logoURI`, optionally `balance`, `price`.
## Token price
```
POST https://zap.dzap.io/v1/token/price
```
Up to 50 addresses.
Map: address → USD price string.
## Token balance
```
POST https://zap.dzap.io/v1/token/balance
```
Map: address → `{ balance, valueUSD }`.
### Examples
```bash details
curl -X POST https://zap.dzap.io/v1/token/details \
-H "Content-Type: application/json" \
-d '{ "chainId": 1, "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "includePrice": true }'
```
```bash prices
curl -X POST https://zap.dzap.io/v1/token/price \
-H "Content-Type: application/json" \
-d '{ "chainId": 1, "tokenAddresses": ["0xA0b...", "0xC02..."] }'
```
# === api/fuse/config.mdx ===
---
title: "Config"
description: "Chains, providers, and platform configuration."
sidebarTitle: "Config"
---
## List supported chains
```
GET https://zap.dzap.io/v1/config/chains
```
Returns the canonical chain list — chain ID, name, native token, RPC URLs, contract addresses.
Map: `chainId` → chain config object.
## List supported providers
```
GET https://zap.dzap.io/v1/config/providers
```
Returns DEXs and bridges DZap routes through, by chain.
Map: `chainId` → array of provider objects with `id`, `name`, `type` (dex/bridge), `logo`.
### Examples
```bash chains
curl https://zap.dzap.io/v1/config/chains
```
```bash providers
curl https://zap.dzap.io/v1/config/providers
```
Always fetch chain + provider config at runtime — new chains and protocols land regularly. Don't hard-code them.
# === api/trade/overview.mdx ===
---
title: "Trade API"
description: "Full Trade API reference at docs.dzap.io."
sidebarTitle: "Trade API"
icon: "arrows-rotate"
---
The Trade API powers `api.dzap.io` — swap, bridge, quotes, gasless, tokens, status, and more. While we consolidate the unified API reference here, the canonical source for the Trade API endpoints is the existing docs.
Full request/response specs, examples, and error codes.
## Quick orientation
- **Base URL** — `https://api.dzap.io`
- **Auth** — API key optional; per-IP fallback. See [Authentication](/api/authentication).
- **Format** — JSON over HTTPS.
- **Rate limits** — see [Rate Limits](/api/rate-limits).
## Common endpoints
| Endpoint | Purpose |
|---|---|
| `POST /v1/swap` | Same-chain swaps (batch) |
| `POST /v1/bridge` | Cross-chain transfers |
| `POST /v1/quotes` | Best-route quotes |
| `POST /v1/buildTx` | Calldata generation |
| `POST /v1/gasless` | Gasless variant |
| `GET /v1/status` | Track transactions |
| `POST /v1/token/details` | Token metadata |
| `POST /v1/token/balance-of` | Account balances |
| `POST /v1/token/price` | Live prices |
| `GET /v1/chains` | Supported chains |
## SDK alternative
Most developers use [`@dzapio/sdk`](/sdk/overview) instead of hitting REST directly — it handles approvals, signing, and retries.
## Migration
A unified API reference (Trade + Fuse in one Mintlify-rendered tab) is on the roadmap. Until then, this page links out to the canonical docs.
# === sdk/overview.mdx ===
---
title: "SDK Overview"
description: "@dzapio/sdk — TypeScript wrapper for every DZap surface."
sidebarTitle: "Overview"
icon: "js"
---
`@dzapio/sdk` is the official TypeScript/JavaScript SDK. It wraps the Trade and Fuse APIs, handles approvals across modes (Permit2, EIP-2612, AutoPermit), and gives you typed quote/build/execute helpers for swap, bridge, and zap.
## Why use the SDK?
- **Type safety** — full TypeScript for every request/response.
- **Approval automation** — one `getAllowance + approve/sign` call covers all four approval modes.
- **Wallet adapters** — works with `viem` `WalletClient` and `ethers.js` `Signer`.
- **Sane defaults** — RPC fallbacks, retry logic, slippage defaults.
## Install
## First call
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xYourAddress',
data: [{
amount: '1000000', // 1 USDC
srcToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
destToken: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
slippage: 1,
}],
});
```
## Where to next
Setup, wallet adapters, RPC config.
`DZapClient.getInstance()` and lifecycle.
Same-chain and cross-chain swaps.
Multi-step intent execution (Fuse).
ERC20, Permit2, EIP-2612, AutoPermit.
Gasless `signGaslessDzapUserIntent`.
# === sdk/installation.mdx ===
---
title: "Installation"
description: "Install, configure RPCs, plug in a wallet."
sidebarTitle: "Installation"
icon: "download"
---
## Install
The SDK is published as `@dzapio/sdk`. Latest stable: `2.0.x`. Targets Node 18+ and modern browsers (with appropriate polyfills for crypto APIs).
## Wallet adapters
The SDK accepts both `viem` and `ethers.js` signers.
```ts viem
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const walletClient = createWalletClient({
account: '0xYourAddress',
chain: arbitrum,
transport: http(),
});
```
```ts ethers
import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider('https://arbitrum.llamarpc.com');
const signer = new ethers.Wallet('0xPrivateKey', provider);
```
Pass either as the `signer` field to `dzap.trade()`, `dzap.zap()`, etc.
Never put private keys in client code or commit them. Use a wallet provider (RainbowKit, ConnectKit, etc.) on the frontend; use a secrets manager on the backend.
## Custom RPC URLs
The SDK ships with sensible defaults but you'll want your own RPCs for production.
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance(undefined, {
1: ['https://eth.llamarpc.com'],
42161: ['https://arbitrum.llamarpc.com'],
8453: ['https://base.llamarpc.com'],
});
```
The first URL in each array is primary; subsequent URLs are fallbacks for read-quorum.
## API key (optional)
```ts
const dzap = DZapClient.getInstance('dzap_xxxxxxxxxxxxxx');
```
API keys raise rate limits and unlock per-route configuration. See [Authentication](/api/authentication).
## Next: [Client](/sdk/client)
# === sdk/client.mdx ===
---
title: "DZapClient"
description: "The SDK entry point and its lifecycle."
sidebarTitle: "Client"
icon: "cube"
---
`DZapClient` is a singleton — one instance per app. All SDK calls flow through it.
## Get an instance
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
// Or with API key + custom RPCs:
const dzap = DZapClient.getInstance('dzap_...', {
42161: ['https://arbitrum.llamarpc.com'],
});
```
`getInstance()` returns the same singleton across calls. The first call wins for `apiKey` and `rpcUrlsByChainId` — subsequent calls reuse those.
## Public methods
| Group | Methods |
|---|---|
| Trade | `getTradeQuotes`, `buildTradeTxn`, `trade`, `tradeGasless`, `getTradeTxnStatus` |
| Zap (Fuse) | `getZapQuote`, `buildZapTxn`, `zap`, `getZapTxnStatus`, `getZapBundleQuote`, `buildZapBundleTx` |
| Tokens | `getAllTokens`, `getTokenDetails`, `getTokenPrices`, `getBalances` |
| Approvals | `getAllowance`, `approve`, `sign` |
| Chain | `getAllSupportedChains`, `getDZapContractAddress`, `getChainConfig` |
| Utility | `decodeTxnData`, `calculatePoints`, `sendBatchCalls`, `waitForBatchTransactionReceipt` |
Each is documented in the dedicated pages: [Trade](/sdk/trade), [Zap](/sdk/zap), [Approvals](/sdk/approvals), [Intents](/sdk/intents), [Tokens & Balances](/sdk/tokens-and-balances), [Utilities](/sdk/utilities).
## Errors
All SDK methods reject with a normalized error:
```ts
try {
await dzap.getTradeQuotes({ ... });
} catch (e: any) {
console.log(e.code); // e.g. "NO_ROUTE_FOUND"
console.log(e.message);
console.log(e.details);
}
```
See [Error Codes](/api/error-codes) for the full catalog.
## Logging
The SDK doesn't log to stdout by default. To attach a logger:
```ts
const dzap = DZapClient.getInstance();
// SDK accepts standard console-like loggers via initialize hooks
// For production, wrap calls in your own observability layer
```
# === sdk/trade.mdx ===
---
title: "Trade"
description: "Same-chain swaps and cross-chain bridges."
sidebarTitle: "Trade"
icon: "arrows-rotate"
---
The trade methods cover same-chain swaps and cross-chain bridges. Same shape for both — set `toChain` to bridge.
## getTradeQuotes
```ts
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xUser',
data: [{
srcToken: '0xaf88...',
destToken: '0x82aF...',
amount: '1000000',
slippage: 1,
// toChain: 8453, // omit for same-chain
}],
});
```
Returns ranked routes for each item in `data`.
## buildTradeTxn
Compiles a chosen quote into transaction calldata.
```ts
const tx = await dzap.buildTradeTxn({
fromChain: 42161,
sender: '0xUser',
refundee: '0xUser',
data: [{
srcToken: '0xaf88...',
destToken: '0x82aF...',
amount: '1000000',
protocol: quotes[0].protocol, // from getTradeQuotes
recipient: '0xUser',
slippage: 1,
}],
});
// tx => { to, data, value, gasLimit }
```
## trade
Build + sign + send in one call. Use this when you have the user's signer at hand.
```ts
const result = await dzap.trade({
request: {
fromChain: 42161,
sender: '0xUser',
refundee: '0xUser',
data: [/* same shape as buildTradeTxn */],
},
signer: walletClient, // viem WalletClient or ethers Signer
});
console.log(result.txnHash);
```
> **Approval required.** If `getAllowance()` reports allowance < amount for the chosen token, call `approve()` first. See [Approvals](/sdk/approvals).
## tradeGasless
The gasless variant — user signs, solver settles.
```ts
import { signGaslessDzapUserIntent } from '@dzapio/sdk';
const signature = await signGaslessDzapUserIntent({
chainId: 42161,
spender: dzap.getDZapContractAddress(42161),
account: '0xUser',
signer: walletClient,
txType: 'swap',
txId: quote.txId,
executorFeesHash: quote.executorFeesHash,
swapDataHash: quote.swapDataHash,
contractVersion: 'v1',
});
await dzap.tradeGasless({
intent: quote,
signature,
txType: 'swap',
});
```
See [Intents](/sdk/intents) for the full gasless flow.
## getTradeTxnStatus
```ts
// Single
const s = await dzap.getTradeTxnStatus({ txHash: '0xabc', chainId: '42161' });
// Batch
const map = await dzap.getTradeTxnStatus({ txIds: '42161-0xabc,8453-0xdef' });
```
For bridges, poll until `s.status === 'completed'`.
# === sdk/zap.mdx ===
---
title: "Zap"
description: "Fuse intent execution from the SDK."
sidebarTitle: "Zap"
icon: "bolt"
---
Zap methods drive **DZap Fuse** — single-signature multi-step flows.
The methods are named `Zap*` but the public product is **Fuse**. They're the same thing — code stays on the legacy name.
## getZapQuote
```ts
const quote = await dzap.getZapQuote({
srcChainId: 42161,
destChainId: 8453,
account: '0xUser',
srcToken: '0xaf88...',
destToken: '0x4200000000000000000000000000000000000006', // Base WETH
amount: '100000000',
recipient: '0xUser',
refundee: '0xUser',
slippage: 1,
});
```
Returns the bundle plan + intent body (txId, hashes, deadline).
## buildZapTxn
```ts
const tx = await dzap.buildZapTxn({
/* same params as getZapQuote */
});
// tx => { to, data, value, gasLimit, txId, steps[] }
```
## zap
Build + sign + send the bundle.
```ts
const result = await dzap.zap({
request: {/* params */},
signer: walletClient,
});
// result.txnHash + result.txId
```
> **Approval required.** Same flow as Trade — `getAllowance()` then `approve()` or `sign()`.
## Bundles
For multi-step intents (bridge → LP-deposit, etc.) use the bundle methods:
```ts
const bundle = await dzap.getZapBundleQuote({
account: '0xUser',
steps: [
{ type: 'bridge', srcChainId: 42161, destChainId: 8453, srcToken: '0xaf88...', destToken: '0x8335...', amount: '100000000' },
{ type: 'zap', srcChainId: 8453, destChainId: 8453, srcToken: '0x8335...', destToken: '0xPool...', action: 'add-liquidity', pool: '0xPool...' },
],
});
const tx = await dzap.buildZapBundleTx({
account: '0xUser',
bundleId: bundle.bundleId,
});
```
## getZapTxnStatus
```ts
const status = await dzap.getZapTxnStatus({ txId: tx.txId });
// status.steps[i] => per-leg progress
```
For UI: render `status.steps` with a per-step indicator. Cross-chain settlement can take seconds to minutes depending on the bridge.
See [Bundle](/products/dzap-fuse/bundle) and [Execution Flow](/products/dzap-fuse/execution-flow) for the conceptual model.
# === sdk/approvals.mdx ===
---
title: "Approvals"
description: "ERC20, Permit2, EIP-2612, and AutoPermit modes."
sidebarTitle: "Approvals"
icon: "check"
---
Before any swap/bridge/zap that spends ERC20s, the DZap router must be approved. The SDK supports four modes — pick `AutoPermit` unless you have a reason not to.
## The four modes
| Mode | How | Gas | Spender |
|---|---|---|---|
| `Default` | Standard ERC20 `approve()` | Yes (one-time) | DZap router |
| `Permit2` | One-time approve to Permit2; sign per-trade | Initial yes, then signature only | Permit2 contract |
| `EIP2612Permit` | Sign permit message; no approval tx | None (signature only) | DZap router |
| `AutoPermit` | EIP2612 if supported, fallback to Permit2 | Best-of-both | Auto |
Most modern tokens support EIP-2612 or are routable through Permit2, so `AutoPermit` covers the long tail.
## Check allowance
```ts
import { ApprovalModes } from '@dzapio/sdk';
const { status, data } = await dzap.getAllowance({
chainId: 42161,
sender: '0xUser',
tokens: [{ address: '0xaf88...', amount: 1_000_000n }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
// data['0xaf88...'] => { allowance: bigint, type: 'dzap' | 'permit2' | 'eip2612' }
```
`type` tells you whether the token will use a direct DZap approval, a Permit2 approval, or an EIP-2612 permit.
## Approve
```ts
if (data['0xaf88...'].allowance < 1_000_000n) {
await dzap.approve({
chainId: 42161,
signer: walletClient,
sender: '0xUser',
tokens: [{ address: '0xaf88...', amount: 1_000_000n }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
approvalTxnCallback: ({ status, txHash }) => {
console.log('approval', status, txHash);
},
});
}
```
## Sign (gasless permits)
For EIP-2612 / Permit2 paths:
```ts
const { data: permits } = await dzap.sign({
chainId: 42161,
sender: '0xUser',
tokens: [{ address: '0xaf88...', amount: '1000000' }],
service: 'swap',
signer: walletClient,
});
// permits['0xaf88...'].permitData → pass to trade()/zap() as `permit`
```
## Recommended flow
`getAllowance()` with `mode: AutoPermit`.
If `allowance < amount`: `approve()` for on-chain or `sign()` for gasless.
Pass the `permit` payload (if any) into `trade()` / `zap()`.
## Common pitfalls
- **Multi-token swaps** — `getAllowance` and `approve` both accept arrays. Don't loop one-by-one; you'll trigger N wallet popups.
- **Service must match** — `service: 'swap'` checks the swap router; `service: 'zap'` checks the zap router. They differ on some chains.
- **Permit deadlines** — gasless permits include a deadline (default ~1 hour). Sign close to execution.
# === sdk/intents.mdx ===
---
title: "Intents"
description: "Gasless intent signing — signGaslessDzapUserIntent."
sidebarTitle: "Intents"
icon: "signature"
---
`signGaslessDzapUserIntent` produces an EIP-712 signature for a Fuse intent. The user pays no gas; the solver settles.
## Three intent shapes
| `txType` | Use case | Type set |
|---|---|---|
| `swap` | Same-chain swap | `DzapUserIntentSwapTypes` |
| `bridge` | Cross-chain transfer (no swap) | `DzapUserIntentBridgeTypes` |
| `swapBridge` | Cross-chain swap + optional destination action | `DzapUserIntentSwapBridgeTypes` |
The SDK picks the right type set when you pass `txType`.
## End-to-end flow
```ts
import { DZapClient, signGaslessDzapUserIntent } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
const dzap = DZapClient.getInstance();
const walletClient = createWalletClient({ account: '0xUser', chain: arbitrum, transport: http() });
// 1. Quote
const quote = await dzap.getZapQuote({
srcChainId: 42161,
destChainId: 8453,
account: '0xUser',
srcToken: '0xaf88...',
destToken: '0x4200000000000000000000000000000000000006',
amount: '100000000',
recipient: '0xUser',
refundee: '0xUser',
slippage: 1,
});
// 2. Sign
const signature = await signGaslessDzapUserIntent({
chainId: 42161,
spender: dzap.getDZapContractAddress(42161),
account: '0xUser',
signer: walletClient,
txType: 'swapBridge',
txId: quote.txId,
executorFeesHash: quote.executorFeesHash,
swapDataHash: quote.swapDataHash,
contractVersion: 'v1',
});
// 3. Submit
await fetch('https://zap.dzap.io/v1/execute', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ intent: quote, signature, txType: 'swapBridge' }),
});
// 4. Track
const status = await dzap.getZapTxnStatus({ txId: quote.txId });
```
## Why hashes are bound at sign time
The intent message you sign includes `executorFeesHash` and `swapDataHash`. These are commitments — the solver can't:
- Inflate fees after you sign (the fee struct is hashed in)
- Substitute a worse swap path (the calldata is hashed in)
If they try either, the on-chain verifier reverts the settlement.
## Deadline
Every intent has a `deadline` (Unix seconds). Past the deadline, the signature is unusable — the solver simply can't settle. Default is generally minutes-to-an-hour; it's set at quote time.
For non-gasless flow, see [Zap](/sdk/zap).
# === sdk/tokens-and-balances.mdx ===
---
title: "Tokens & Balances"
description: "Token lists, prices, balances, and metadata."
sidebarTitle: "Tokens & Balances"
icon: "coins"
---
The SDK includes typed wrappers for the public token endpoints. All return cached prices where possible — use them in tight UI loops without hammering the API.
## getAllTokens
```ts
const tokens = await dzap.getAllTokens(1); // Ethereum
const withPrices = await dzap.getAllTokens(1, undefined, '0xUser'); // include balances
```
## getTokenDetails
```ts
const usdc = await dzap.getTokenDetails(
'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address
1, // chainId
'0xUser', // account (optional)
true, // includeBalance
true, // includePrice
);
```
## getTokenPrices
```ts
const prices = await dzap.getTokenPrices(
['0xA0b...', '0xC02...'],
1,
);
// prices => { '0xA0b...': '1.00', '0xC02...': '3450.12' } (USD strings or null)
```
## getBalances
```ts
const balances = await dzap.getBalances(
8453, // chainId
'0xUser',
);
// Native + ERC20 balances with USD valuation
```
## Tips
- **Native token** — comes back under the sentinel address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`.
- **Price freshness** — DZap aggregates prices across CoinGecko + protocol-native sources. Stale prices (>5min) are flagged in the response.
- **Decimals** — always check `decimals` before formatting. USDC is 6, WETH is 18.
# === sdk/utilities.mdx ===
---
title: "Utilities"
description: "decodeTxnData, points, batch calls."
sidebarTitle: "Utilities"
icon: "wrench"
---
A handful of helpers that don't fit the trade/zap categories.
## decodeTxnData
Decodes a DZap transaction's input data into a readable structure — useful for indexing or debugging.
```ts
const decoded = dzap.decodeTxnData({
chainId: 42161,
data: '0x...',
});
// => { method, args: { ... } }
```
## calculatePoints
Estimates DZap loyalty points for a given action — used by partners surfacing rewards in their UI.
```ts
const points = await dzap.calculatePoints({
chainId: 1,
account: '0xUser',
amount: '1000000000', // wei
service: 'swap',
});
```
## sendBatchCalls
Bundles multiple write calls into one transaction (where the chain supports it — EIP-5792 / multicall fallback).
```ts
const result = await dzap.sendBatchCalls({
chainId: 1,
signer: walletClient,
calls: [
{ to: '0xToken', data: encodeApprove(...) },
{ to: '0xToken', data: encodeApprove(...) },
],
});
```
## waitForBatchTransactionReceipt
Companion to `sendBatchCalls`. Waits until all sub-calls have confirmed.
```ts
await dzap.waitForBatchTransactionReceipt({
chainId: 1,
batchId: result.batchId,
});
```
## Chain helpers
```ts
const chains = await dzap.getAllSupportedChains(); // map of chainId → config
const config = await dzap.getChainConfig(8453); // single chain
const router = dzap.getDZapContractAddress(8453); // string
```
Use these instead of hard-coding addresses or chain IDs — both shift over time.
# === cookbook/first-swap.mdx ===
---
title: "Your First Swap"
description: "End-to-end same-chain swap, with approvals and status tracking."
sidebarTitle: "First swap"
icon: "arrows-rotate"
---
A complete swap on Arbitrum: 100 USDC → WETH. Copy, paste, run.
## Setup
```ts
import { DZapClient, ApprovalModes } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({
account,
chain: arbitrum,
transport: http(),
});
const dzap = DZapClient.getInstance();
const USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const WETH = '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1';
const AMOUNT = '100000000'; // 100 USDC (6 decimals)
```
## Steps
```ts
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: account.address,
data: [{
srcToken: USDC,
destToken: WETH,
amount: AMOUNT,
slippage: 1,
}],
});
const best = quotes[0].quotes[0];
console.log(`Best: ${best.protocol}, output ${best.amountOut}`);
```
```ts
const allowance = await dzap.getAllowance({
chainId: 42161,
sender: account.address,
tokens: [{ address: USDC, amount: BigInt(AMOUNT) }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
const needsApproval = allowance.data[USDC].allowance < BigInt(AMOUNT);
if (needsApproval) {
await dzap.approve({
chainId: 42161,
signer: walletClient,
sender: account.address,
tokens: [{ address: USDC, amount: BigInt(AMOUNT) }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
}
```
```ts
const result = await dzap.trade({
request: {
fromChain: 42161,
sender: account.address,
refundee: account.address,
data: [{
srcToken: USDC,
destToken: WETH,
amount: AMOUNT,
protocol: best.protocol,
recipient: account.address,
slippage: 1,
}],
},
signer: walletClient,
});
console.log(`Sent: ${result.txnHash}`);
```
```ts
const status = await dzap.getTradeTxnStatus({
txHash: result.txnHash,
chainId: '42161',
});
console.log(status.status); // 'completed' once mined
```
## What can go wrong
- **`NO_ROUTE_FOUND`** — pair is too thin or not yet supported. Try a different amount or token.
- **`SLIPPAGE_TOO_TIGHT`** — bump slippage from 1 to 2.
- **Approval fails** — make sure your wallet has gas (ETH on Arbitrum).
See [Error Codes](/api/error-codes) for the full catalog.
## Going further
- [Cross-chain bridge](/cookbook/cross-chain-bridge) — same flow with `toChain`.
- [Approvals reference](/sdk/approvals) — Permit2 vs EIP-2612 vs AutoPermit.
- [Trade SDK](/sdk/trade) — every method, every option.
# === cookbook/cross-chain-bridge.mdx ===
---
title: "Cross-Chain Bridge"
description: "Move USDC from Arbitrum to Base in one transaction."
sidebarTitle: "Cross-chain bridge"
icon: "bridge"
---
Bridging on DZap is the same `getTradeQuotes` / `trade` flow as a swap — you just set `toChain`.
## End-to-end
```ts
import { DZapClient, ApprovalModes } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({ account, chain: arbitrum, transport: http() });
const dzap = DZapClient.getInstance();
const USDC_ARB = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
// 1. Quote
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: account.address,
data: [{
srcToken: USDC_ARB,
destToken: USDC_BASE,
amount: '50000000', // 50 USDC
toChain: 8453,
slippage: 1,
}],
});
const best = quotes[0].quotes[0];
// 2. Approve
await dzap.approve({
chainId: 42161,
signer: walletClient,
sender: account.address,
tokens: [{ address: USDC_ARB, amount: 50_000_000n }],
service: 'swap',
mode: ApprovalModes.AutoPermit,
});
// 3. Bridge
const result = await dzap.trade({
request: {
fromChain: 42161,
sender: account.address,
refundee: account.address, // refund here if destination fails
data: [{
srcToken: USDC_ARB,
destToken: USDC_BASE,
amount: '50000000',
toChain: 8453,
protocol: best.protocol,
recipient: account.address, // could be a different address
slippage: 1,
}],
},
signer: walletClient,
});
// 4. Track (cross-chain settlement is async)
async function waitForSettlement() {
for (let i = 0; i < 60; i++) {
const status = await dzap.getTradeTxnStatus({
txIds: `42161-${result.txnHash}`,
});
if (status.status === 'completed') return status;
if (status.status === 'failed') throw new Error('bridge failed');
await new Promise(r => setTimeout(r, 5000));
}
throw new Error('timeout');
}
const finalStatus = await waitForSettlement();
console.log('settled:', finalStatus);
```
## Bridge quirks
- **`refundee` matters.** If the destination side fails, funds return to `refundee` on the source chain. Use a wallet you control.
- **`recipient` can differ from `sender`.** Useful when you're paying on someone else's behalf — they receive on the destination chain.
- **Settlement time varies.** Across is seconds; CCTP is ~13 minutes; Allbridge varies by route. Check `quotes[0].quotes[0].estimatedDuration`.
- **Pre-bridge approval is on source chain only.** No additional approval needed on the destination side; the bridge contract handles destination disbursement.
## When to use Fuse instead
If your goal is "bridge, then do something on the destination" (e.g. add liquidity, mint NFT), use [Fuse Bundle](/products/dzap-fuse/bundle) — one signature for the whole journey.
## Next
- [SDK Trade reference](/sdk/trade)
- [Trade API → Bridge](/api/trade/overview)
- [Fuse for multi-step journeys](/products/dzap-fuse/overview)
# === cookbook/zap-into-lp.mdx ===
---
title: "Zap into LP"
description: "USDC on one chain → LP position on another, in one signature."
sidebarTitle: "Zap into LP"
icon: "layer-group"
---
The Fuse killer demo: take USDC on Arbitrum and end up with a USDC/WETH Uniswap V3 position on Base — without the user signing five transactions.
## The bundle
```ts
import { DZapClient } from '@dzapio/sdk';
const dzap = DZapClient.getInstance();
const bundleQuote = await dzap.getZapBundleQuote({
account: '0xUser',
steps: [
// Step 1: bridge USDC Arbitrum → Base
{
type: 'bridge',
srcChainId: 42161,
destChainId: 8453,
srcToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
destToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
amount: '500000000', // 500 USDC
},
// Step 2: zap into the USDC/WETH 0.05% pool
{
type: 'zap',
srcChainId: 8453,
destChainId: 8453,
srcToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
destToken: '0xd0b53D9277642d899DF5C87A3966A349A798F224',
action: 'add-liquidity',
pool: '0xd0b53D9277642d899DF5C87A3966A349A798F224',
},
],
recipient: '0xUser',
refundee: '0xUser',
slippage: 1,
});
const tx = await dzap.buildZapBundleTx({
account: '0xUser',
bundleId: bundleQuote.bundleId,
});
// Then sign + send tx, OR use signGaslessDzapUserIntent for gasless flow.
```
## Tracking
```ts
const status = await dzap.getZapTxnStatus({ txId: tx.txId });
// status.steps => [
// { type: 'bridge', protocol: 'across', status: 'completed', txHash: '0x...' },
// { type: 'zap', protocol: 'uniswap-v3', status: 'completed', txHash: '0x...' },
// ]
```
For UI: render `status.steps` with a per-step indicator. The bridge step settles in tens of seconds; the LP-deposit step settles in seconds once the bridge lands.
## Gasless variant
Same shape, but the user signs an EIP-712 intent instead of submitting a transaction. The solver pays gas. See [Fuse → Gasless](/products/dzap-fuse/gasless).
## Variations
- **Replace `add-liquidity` with `deposit`** for vault flows (Yearn, Beefy, Aave).
- **Add a 3rd step** for stake/lock actions on the deposit token.
- **Concentrated liquidity** — pass `poolDetails: { lowerTick, upperTick }` in the zap step.
## Caveats
- LP zaps are pool-specific. Confirm the destination token is a real LP/pool address, not just a token.
- Slippage applies end-to-end. A tight slippage on a complex bundle can fail more often than a single swap; use 1-2% for typical Uniswap V3 entries.
- For exotic pools (Balancer weighted, Curve metapools), check that the bundle resolves with `protocol` you expect.
## Next
- [Bundle API reference](/api/fuse/bundle)
- [Execution flow](/products/dzap-fuse/execution-flow)
- [SDK zap methods](/sdk/zap)
# === cookbook/partner-fees.mdx ===
---
title: "Partner Fees"
description: "Add your platform fee on top of DZap routing."
sidebarTitle: "Partner Fees"
icon: "money-bill-trend-up"
---
When you integrate DZap into a wallet, dashboard, or dApp, you can charge your **own fee on top of** DZap's protocol fee. The amount accrues to an address you control — automatically, with no separate transaction.
Partner Fees are a pattern, not a separate product. The hooks are part of the standard SDK — you add fee fields, DZap respects them, and the fee accrues to the address you specify.
## How it works
Pass `partnerFee` in the quote request — basis points + recipient address.
```ts
const quotes = await dzap.getTradeQuotes({
fromChain: 42161,
account: '0xUser',
data: [{
srcToken: '0xUSDC',
destToken: '0xWETH',
amount: '1000000',
slippage: 1,
partnerFee: {
recipient: '0xYourPlatform',
bps: 30, // 0.3%
},
}],
});
```
Quote response includes both the user-facing output (net of all fees) and the breakdown (DZap protocol fee, your partner fee, gas).
Build + send via `trade()` or `zap()`. Your fee accrues automatically — no separate transaction.
Your address receives the partner fee in the destination token (or source, depending on flow). Track via on-chain analytics or a server-side ledger.
## Fee fields
| Field | Type | Notes |
|---|---|---|
| `partnerFee.recipient` | string | Your address that receives the fee |
| `partnerFee.bps` | number | Basis points (1 bps = 0.01%) |
| `partnerFee.flat` | string | Optional flat amount in source token wei |
You can use either `bps` or `flat`; not both.
## Combining with gasless
Partner Fees + gasless: your fee is committed in the EIP-712 intent (in `executorFeesHash`). Solvers can't strip it after signing.
```ts
// In a gasless flow, partnerFee bakes into the intent
const intent = await dzap.getZapQuote({
...,
partnerFee: { recipient: '0xYourPlatform', bps: 30 },
});
```
## When to ask for a partnership
If you're routing meaningful volume (~$1M+/month) and want a custom fee tier, joint announcements, or a dedicated support channel — see [Partnership Requests](/products/partnerships).
## See also
- [Fees](/products/fees) — DZap's own fee schedule.
- [Partnerships](/products/partnerships) — request a custom tier.
- [SDK Trade](/sdk/trade) — the underlying trade methods.
# === cookbook/ai-trade-bot.mdx ===
---
title: "AI Trade Bot"
description: "Build an agent that swaps with limits and confirmations."
sidebarTitle: "AI trade bot"
icon: "robot"
---
## What's coming
A complete recipe for an AI agent that:
- Monitors prices and on-chain conditions.
- Plans swaps within bounded authority (max trade size, slippage caps, daily spend).
- Surfaces every plan for human confirmation before execution.
- Logs decisions for audit + replay.
## In the meantime
While the recipe is finalized, the building blocks are documented:
The runtime that drives the agent.
Session keys, confirmations, threat model.
Prompt patterns that work.
What the agent can call.
## Track release
[Changelog](/resources/changelog) · `@dzap_io` on X · [Discord](https://discord.com/invite/aRHESJB9md).
# === cookbook/widget-integration.mdx ===
---
title: "Widget Integration"
description: "Embed DZap swap UI in your app."
sidebarTitle: "Widget integration"
icon: "browser"
---
## What's coming
The DZap embeddable widget will let you drop a full swap/bridge UI into any web app:
- React + plain JS bundles
- Themeable to match your brand
- Pre-fillable from URL params (chain, tokens, amount)
- Wallet adapter passthrough
- Compatible with [Partner Fees](/cookbook/partner-fees) for monetization
## In the meantime
If you want to give users a swap experience today without building UI from scratch, two paths:
### 1. Deep links to the DZap app
Generate pre-filled links to `app.dzap.io`:
```ts
const url = await sdk.getTool('SwapLinkGeneratorTool').execute({
fromChain: 42161,
srcToken: '0xaf88...',
destToken: '0x82aF...',
amount: '100000000',
});
window.open(url, '_blank');
```
### 2. Roll your own with the SDK
`@dzapio/sdk` covers everything the widget will eventually wrap. See [First Swap](/cookbook/first-swap) for the basic shape.
## Track release
[Changelog](/resources/changelog) · `@dzap_io` on X · [Discord](https://discord.com/invite/aRHESJB9md).
# === resources/glossary.mdx ===
---
title: "Glossary"
description: "Words that recur in DZap docs."
sidebarTitle: "Glossary"
icon: "book"
---
The glossary is being filled in. For now, the most-used terms:
- **Core** — DZap's swap + bridge aggregator product.
- **Fuse** — DZap's intent execution layer (called `Zap*` in code).
- **ZapBot** — DZap's reasoning agent.
- **Bundle** — multi-step Fuse intent settled atomically.
- **Solver** — actor that picks up signed intents and executes.
- **Intent** — EIP-712 message describing an outcome.
Full glossary lands here as the docs stabilize. Track via the [changelog](/resources/changelog).
# === resources/security.mdx ===
---
title: "Security"
description: "Audit reports, disclosure, and the DZap security model."
sidebarTitle: "Security"
icon: "shield"
---
The full security overview, audit reports, and partner disclosures live under [Security & Audits](/products/security-and-audits).
## Quick links
Top-level audits across all DZap products.
Per-version Fuse contract audits.
Older reports, still maintained.
Verify what you're spending tokens against.
## Reporting
Email `support@dzap.io` with `[SECURITY]` in the subject. We acknowledge within 24 hours.
# === resources/changelog.mdx ===
---
title: "Changelog"
description: "What's new across DZap products."
sidebarTitle: "Changelog"
icon: "list"
---
Significant changes across DZap's products, SDK, AI stack, and APIs will land here.
For per-package version history in the meantime, see GitHub releases:
- [`@dzapio/sdk`](https://github.com/dzap-io/sdk/releases)
- [`dzapai`](https://github.com/dzap-io/dzapai/releases)
- [`DZapZappingContracts`](https://github.com/DZapIO/DZapZappingContracts/releases)
# === resources/brand-assets.mdx ===
---
title: "Brand Assets"
description: "Logos, colors, and usage guidelines."
sidebarTitle: "Brand assets"
icon: "palette"
---
The full DZap asset library — logos, icons, lock-ups, partner assets — lives in:
Official repo for all DZap brand assets.
Pull from there for any integration or marketing surface.
## Quick reference
### Colors
| Role | Hex |
|---|---|
| Primary (DZap green) | `#93E900` |
| Light | `#B4F23F` |
| Dark | `#5FA500` |
### Wordmark
Always **DZap** — capital D, lowercase z, lowercase a, lowercase p. Not "Dzap", "DZAP", or "D-Zap" outside the stylized brand wordmark itself.
### Product names
- **DZap Core** — swap and bridge aggregator.
- **DZap Fuse** — single-click intent execution layer.
- **DZap AI** — the AI stack (CLI, MCP, Skills, Tools).
In code, Fuse features are still named `Zap*`. Use the **Fuse** name in user-facing surfaces.
## Logo usage
✅ **Do**:
- Use SVG where possible (scales cleanly).
- Maintain clear space around the wordmark.
- Pair with the official primary color or neutral background.
❌ **Don't**:
- Distort, rotate, or recolor the logo.
- Combine with another logo in a way that implies endorsement without approval.
## Press / partnership
Reach out at `partnerships@dzap.io` for press kits, brand approvals, and partner co-marketing.