0xFOX API & SDK: Complete Developer Guide

Whether you are building a DeFi aggregator, a portfolio tracker, or an automated trading system, the 0xFOX API gives you programmatic access to the entire platform: intent submission, balance queries, health monitoring, and agent management. This guide covers the REST API endpoints, the TypeScript SDK (FoxClient), authentication, rate limits, and best practices.

The API follows an intent-based architecture. Instead of constructing raw blockchain transactions, you submit intents— declarations of what you want to achieve — and the 0xFOX matching engine handles execution, routing, simulation, and settlement. This dramatically simplifies cross-chain operations and eliminates the need to manage nonces, gas estimation, or chain-specific transaction formats.

Architecture Overview

The 0xFOX API is served by fox-server, an Axum 0.8 application that orchestrates the entire swap pipeline. When you submit an intent, the server passes it through the matching engine, Shadow EVM simulation, MEV Shield analysis, and settlement layer. The API exposes this pipeline through clean REST endpoints with JSON request/response bodies.

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token. Keys are generated from the 0xFOX dashboard under Settings. Each key is scoped to a specific set of permissions (read-only, trade, admin) and tied to an identity.

The TypeScript SDK handles authentication automatically. Pass your API key when constructing the FoxClient instance:

Core API Endpoints

Health Check

GET /v1/health returns the system status, including matching engine availability, supported chains, and current latency metrics. Use this to verify connectivity and monitor service health in production.

Submit Intent

POST /v1/intents is the primary endpoint. Submit a bridge or swap intent with source chain, destination chain, token, amount, and recipient address. The server returns an intent ID that you use to track status.

Query Intent Status

GET /v1/intents/:id returns the current status of an intent: matching, simulating, settling, complete, or failed. The response includes transaction hashes for both source and destination chains once settlement is complete.

Virtual Balances

GET /v1/balances returns V-Ledger balances for the authenticated user across all supported chains and tokens. These are off-chain balances that can be used for instant transfers without gas costs.

Deposit and Withdraw

POST /v1/deposit and POST /v1/withdraw move assets between on-chain wallets and the V-Ledger. Deposits require an on-chain transaction (gas is paid); withdrawals are initiated off-chain and settled by the system.

TypeScript SDK: FoxClient

The @0xfox-org/sdk package provides a typed TypeScript client that wraps all API endpoints. Install it via npm:

The SDK provides full TypeScript types for all request and response objects, enabling IDE autocompletion and compile-time type checking. All methods return Promises and support both async/await and callback patterns.

Key Methods

• fox.health()— Check system status and supported chains.
• fox.submitIntent(params)— Submit a bridge or swap intent.
• fox.getIntent(id)— Query intent status and settlement details.
• fox.getBalances()— Fetch V-Ledger balances.
• fox.deposit(params)— Initiate an on-chain deposit to V-Ledger.
• fox.withdraw(params)— Withdraw from V-Ledger to on-chain wallet.

Rate Limits

The API enforces rate limits per API key. Standard keys allow 60 requests per minute for read endpoints and 10 requests per minute for write endpoints (intent submission, deposit, withdraw). Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Enterprise keys with higher limits are available for high-volume integrators.

Error Handling

All errors follow a consistent JSON format with error (machine-readable code),message (human-readable description), and details (additional context). HTTP status codes follow REST conventions: 400 for bad requests, 401 for auth failures, 429 for rate limits, and 500 for internal errors. The SDK throws typed exceptions that you can catch and handle programmatically.

Best Practices

• Poll with backoff: After submitting an intent, poll the status endpoint with exponential backoff (start at 1s, max 10s). Most intents resolve in under 5 seconds.
• Use V-Ledger for frequent transfers: Deposit once, then use virtual balances for subsequent transfers to avoid on-chain gas costs.
• Cache health responses: The health endpoint data is stable for 30+ seconds. Cache it to stay within rate limits.
• Handle simulation failures gracefully: If the Shadow EVM rejects a transaction, the error includes the revert reason. Use it to adjust parameters and retry.