Developer Docs

API Reference

Complete reference for all Alkizen API endpoints. All endpoints are proxied through our backend — API keys are never exposed to the frontend.

Back to Documentation

Overview

Base URL

https://api.alkizen.exchange

Authentication

SIWE (Sign-In With Ethereum) bearer token

Rate Limits

100 req/min per wallet, 500 req/min per IP

All API calls to Relay are proxied through the Alkizen backend. This ensures API keys remain secret, platform fees are applied atomically, and all transactions are recorded for the leaderboard, quests, and referral tracking. Public endpoints (tokens, chains) do not require authentication. Authenticated endpoints require a valid SIWE session token in the Authorization header.

Endpoints

GET/api/relay/tokens

List Supported Tokens

Returns a list of all supported tokens across all chains. Optionally filter by chain ID or search by token name, symbol, or contract address. Results are cached for 30 minutes (5 minutes for search queries) to ensure fast responses.

Query Parameters

chainId

number

Filter tokens by a specific blockchain chain ID (e.g., 1 for Ethereum, 8453 for Base, 792703809 for Solana).

search

string

Search tokens by name, symbol, or contract address. Minimum 1 character.

Response Example

{
  "currencies": [
    {
      "chainId": 1,
      "address": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "name": "Ether",
      "decimals": 18,
      "logoUrl": "https://assets.relay.link/icons/1/light.png",
      "verified": true
    },
    {
      "chainId": 8453,
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "logoUrl": "https://assets.relay.link/icons/currencies/usdc.png",
      "verified": true
    }
  ]
}

GET/api/relay/chains

List Supported Chains

Returns all blockchains supported by Alkizen, including chain ID, name, native currency, explorer URLs, and RPC endpoints. Use this to populate chain selectors and validate user input.

Response Example

{
  "chains": [
    {
      "id": 1,
      "name": "ethereum",
      "displayName": "Ethereum",
      "httpRpcUrl": "https://eth.llamarpc.com",
      "explorerUrl": "https://etherscan.io",
      "iconUrl": "https://assets.relay.link/icons/1/light.png",
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      }
    },
    {
      "id": 8453,
      "name": "base",
      "displayName": "Base",
      "httpRpcUrl": "https://mainnet.base.org",
      "explorerUrl": "https://basescan.org",
      "iconUrl": "https://assets.relay.link/icons/8453/light.png",
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      }
    }
  ]
}

POST/api/relay/quoteAUTH

Get Swap/Bridge Quote

Fetches a real-time price quote for a swap or bridge operation. The quote includes the expected output amount, gas estimate, platform fee breakdown, and execution data. Quotes are valid for approximately 30 seconds. The platform fee (configurable by admin, typically 0.1% - 0.5%) is applied on top of Relay's native fees and is shown transparently in the response.

Request Body

originChainId

numberrequired

Chain ID of the source token.

destinationChainId

numberrequired

Chain ID of the destination token.

originCurrency

stringrequired

Contract address of the source token (use 0x0...0 for native tokens).

destinationCurrency

stringrequired

Contract address of the destination token.

amount

stringrequired

Amount to swap in the source token's smallest unit (wei, lamports, etc.).

recipient

string

Recipient wallet address. Defaults to the sender if not provided.

Response Example

{
  "quote": {
    "inputAmount": "1000000000000000000",
    "outputAmount": "2487350000",
    "rate": "2487.35",
    "estimatedGas": "0.002",
    "platformFee": {
      "percentage": "0.3%",
      "amount": "7462050",
      "currency": "USDC"
    },
    "relay": {
      "requestId": "0xabc123...",
      "estimatedTime": 12
    }
  }
}

POST/api/relay/executeAUTH

Execute Transaction

Executes a previously quoted swap, bridge, or payment. The user must have already signed the transaction data returned by the quote endpoint. This triggers the actual on-chain execution via Relay. The response includes a request ID for status tracking. All transactions are recorded in the database with full audit trail.

Request Body

quoteId

stringrequired

The quote ID returned by the /quote endpoint.

signature

stringrequired

The user's wallet signature for the transaction.

walletAddress

stringrequired

The wallet address executing the transaction.

Response Example

{
  "transaction": {
    "relayRequestId": "0xabc123def456...",
    "status": "pending",
    "type": "swap",
    "originChainId": 1,
    "destinationChainId": 8453,
    "inputAmount": "1000000000000000000",
    "expectedOutput": "2487350000",
    "platformFee": "7462050",
    "createdAt": "2026-02-21T12:00:00Z"
  }
}

GET/api/relay/status/:requestIdAUTH

Check Transaction Status

Polls the status of a transaction by its Relay request ID. Returns the current state (pending, confirming, completed, failed), along with on-chain transaction hashes for both the origin and destination chains. The frontend polls this endpoint every 3 seconds until the transaction reaches a terminal state.

Query Parameters

requestId

stringrequired

The Relay request ID returned by the execute endpoint.

Response Example

{
  "status": "completed",
  "originTxHash": "0xdef789...",
  "destinationTxHash": "0xghi012...",
  "completedAt": "2026-02-21T12:00:12Z",
  "details": {
    "inputAmount": "1000000000000000000",
    "outputAmount": "2487350000",
    "executionTimeMs": 11500
  }
}

POST/api/dca/createAUTH

Create DCA Order

Creates a new Dollar-Cost Averaging order. The order will be automatically executed at the specified frequency by the backend scheduler. Each execution generates a fresh quote and submits to Relay. Failed executions are retried up to 3 times before pausing the order and notifying the user.

Request Body

sourceToken

stringrequired

Contract address of the token to spend.

targetToken

stringrequired

Contract address of the token to buy.

sourceChainId

numberrequired

Chain ID of the source token.

targetChainId

numberrequired

Chain ID of the target token.

amountPerInterval

stringrequired

Amount to swap per interval in the source token's smallest unit.

frequency

stringrequired

Execution frequency: "hourly", "daily", "weekly", or "monthly".

totalIntervals

numberrequired

Total number of executions before the DCA order completes.

Response Example

{
  "dca": {
    "id": "dca_abc123",
    "status": "active",
    "sourceToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "targetToken": "0x0000000000000000000000000000000000000000",
    "frequency": "weekly",
    "amountPerInterval": "50000000",
    "totalIntervals": 12,
    "executionsDone": 0,
    "nextExecutionAt": "2026-02-28T12:00:00Z",
    "createdAt": "2026-02-21T12:00:00Z"
  }
}

POST/api/limit/createAUTH

Create Limit Order

Places a conditional limit order that executes when the target price is reached. The off-chain price oracle checks market conditions every 10 seconds. When the condition is met, a Relay intent is created and executed immediately. Limit orders can be cancelled at any time before execution.

Request Body

sourceToken

stringrequired

Contract address of the token to sell.

targetToken

stringrequired

Contract address of the token to buy.

sourceChainId

numberrequired

Chain ID of the source token.

targetChainId

numberrequired

Chain ID of the target token.

amount

stringrequired

Total amount to sell in the source token's smallest unit.

targetPrice

stringrequired

Target price condition in USD.

direction

stringrequired

"above" or "below" — execute when price goes above or below the target.

expiresAt

string

ISO 8601 expiry timestamp. Order is cancelled if not filled by this time.

Response Example

{
  "limitOrder": {
    "id": "lmt_def456",
    "status": "open",
    "sourceToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "targetToken": "0x0000000000000000000000000000000000000000",
    "amount": "1000000000",
    "targetPrice": "2800.00",
    "direction": "below",
    "currentPrice": "3124.50",
    "expiresAt": "2026-03-21T12:00:00Z",
    "createdAt": "2026-02-21T12:00:00Z"
  }
}

GET/api/leaderboard

Get Leaderboard

Returns the ranked leaderboard of top Alkizen users. Rankings are calculated based on a composite score of total trading volume, quests completed, and referral points. The leaderboard is recalculated every hour. Results are paginated with 10 entries per page.

Query Parameters

page

number

Page number (default: 1). Each page contains 10 entries.

limit

number

Entries per page (default: 10, max: 100).

Response Example

{
  "leaderboard": [
    {
      "rank": 1,
      "walletAddress": "0x1234...abcd",
      "totalVolume": "1250000.00",
      "questsCompleted": 47,
      "referralCount": 23,
      "score": 98750,
      "badges": ["whale", "early_adopter", "quest_master"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1847,
    "totalPages": 185
  }
}

Error Handling

All error responses follow a consistent format. HTTP status codes are used to indicate the type of error. The response body always contains a human-readable message and an error code for programmatic handling.

{
  "statusCode": 400,
  "error": "BAD_REQUEST",
  "message": "Invalid chain ID: 99999"
}

400Bad Request — Invalid parameters or missing required fields

401Unauthorized — Missing or invalid authentication token

404Not Found — Resource does not exist

429Rate Limited — Too many requests, slow down

500Server Error — Internal error, contact support

For the underlying Relay API documentation, visit docs.relay.link