API

About

The EXTRA WALLET API provides a comprehensive suite of endpoints for interacting with multiple blockchain networks, querying balances, fetching token prices, estimating gas fees, checking transaction histories, and managing user payment credits.

This page contains general principles, conventions, and information that should be understood before exploring specific API modules.

Authentication

Certain endpoints — such as Wallet Recovery Tool — require authentication via an API Key.

When calling protected endpoints, you must include your API key in the request headers:

x-api-key: your_api_key_here

Endpoints regarding public data (like gas, prices, and balances) generally do not require API key authentication.

Request & Response Format

• Content-Type: All POST and PUT requests expect a JSON payload (application/json).
• Standard Responses: A successful request typically returns a JSON object with the requested information mapped to corresponding fields. Error responses will have a clear description and return a standard HTTP error code (e.g., 400 Bad Request, 500 Internal Server Error).

Rate Limiting

The API includes middleware rate limiters. If you submit too many requests in a short time frame, you will receive an HTTP 429 Too Many Requests status code. Please respect rate limits to avoid being temporarily blocked.

Networks

Most of the routes require you to specify the network(s) you want to interact with. For that the network_ids are used. Here is the list of supported networks and their respectful ids.

Network	Id
Ethereum	ethereum
Optimism	optimism
Binance Smart Chain(BSC)	bsc
Polygon	polygon
Sonic	sonic
Base	base
Arbitrum	arbitrum
Avalanche	avalanche
Tron	tron
Ethereum Classic	ethereum-classic
Ton	ton
Bitcoin	bitcoin
Litecoin	litecoin
Solana	solana
Sui	sui
Aptos	aptos
Dogecoin	dogecoin
Ripple(Xrp)	ripple
Cardano	cardano
Bitcoin Cash	bch
Polkadot	polkadot
Testnet	testnet

Developer Info

Tech Stack

• Framework: Express.js
• Language: TypeScript
• Validation & Serialization: Zod
• Database ORM: Drizzle ORM (PostgreSQL)
• API Documentation: Swagger UI & Zod-to-OpenAPI
• Testing: Vitest
• Logging: Pino

Prerequisites

• Node.js (v22)
• Yarn (v1.22+)
• PostgreSQL
• Redis

Getting Started

1. Install Dependencies

   yarn

2. Environment Variables Copy the provided .env.template to .env and fill in the required values for your database, Redis instance, and other features.

   cp .env.template .env

3. Start Development Server

   yarn dev

   The server will start with hot-reloading enabled.

Available Scripts

• yarn dev: Start the development server with hot-reloading (uses tsx and pino-pretty).
• yarn build: Verify types, run ESLint, and compile the application using tsup.
• yarn start: Run the compiled production build from dist/index.js.
• yarn test: Run the test suite using Vitest.
• yarn lint: Run ESLint to review code style.
• yarn lint:fix: Run ESLint and automatically fix detected problems.
• yarn run:jobs: Execute scheduled background jobs manually.
• yarn db:generate:general: Generate constraints and schemas for the general configuration using drizzle-kit.
• yarn db:migrate:general: Run Drizzle migrations for the general database.
• (See package.json for similar db: scripts corresponding to payment_system and hd-wallet-tools)

Project Structure

• src/api/: Contains controllers and route definitions for various modules (e.g., balance, gas, price, payment, history).
• src/common/: Shared utilities, middleware (rate limiting, error handlers), and models.
• src/drizzle/: Database schemas, config, and migration scripts separated by domains (general, payment_system, hd-wallet-tools).
• src/jobs/: Scheduled background cron jobs for indexing and upkeep.
• src/api-docs/: OpenAPI (Swagger) configuration and schema definitions powered by Zod.

Database Management

The project uses Drizzle ORM to manage multiple segregated schemas/databases. Make sure to run the appropriate migration commands (yarn db:migrate:*) before starting the application, especially if working on payment systems or admin tools. Seed scripts are provided for initializing basic configuration data.

API Documentation

When running locally with ENABLE_SWAGGER=true in your .env, you can access the Swagger UI directly on the local server or retrieve the OpenAPI specification at /swagger.json.

• Built and maintained by the EXTRA WALLET team.
• Source: API