Help Center/HOW TO Guides/API Integration
Back to Guides
Advanced · 30 minutes

How to Integrate via API

Build on top of IPX with our RESTful API — access market data, trading, and bonding curve endpoints

What You'll Learn

Generate and manage your API keys
Authenticate requests with Bearer tokens
Fetch market data and order books
Query trade history and chart data
Access bonding curve pricing and quotes
Handle rate limiting and error codes
Set up webhooks for real-time events
Best practices for production integrations

API Overview

The IPX API is a RESTful interface that returns JSON responses. It enables developers to build trading bots, portfolio dashboards, analytics tools, and custom integrations on top of the IPX platform. All endpoints operate over HTTPS and are accessible from any programming language.

Quick Reference

Base URL

https://ipx.exchange/api

Authentication

Bearer token in Authorization header

Rate Limit

100 requests / minute per key

Format

JSON request/response bodies

Getting Started

1

Generate Your API Key

Navigate to Settings → Developer → API Keys and click "Generate New Key".

Path: Settings → Developer → Generate API Key

  1. Give your key a descriptive label (e.g., "Trading Bot - Production")
  2. Select permissions: Read Only, Read + Trade, or Full Access
  3. Optionally restrict to specific IP addresses for security
  4. Click "Generate"

Critical: Your API secret is shown only once. Copy it immediately and store it securely (e.g., environment variable, secrets manager). If you lose it, you'll need to generate a new key.

2

Authenticate Your Requests

Include your API key as a Bearer token in the Authorization header of every request:

typescript
const response = await fetch('https://ipx.exchange/api/trading/market', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Security: Never expose your API key in client-side JavaScript. Always call the API from a server-side environment (Node.js, Python, etc.) or use a proxy endpoint.

3

Explore Core Endpoints

The IPX API provides these primary endpoints:

GET/api/trading/market

Returns current market data for all listed tokens including price, 24h volume, market cap, and price change percentages.

GET/api/trading/orderbook

Real-time order book with bid/ask prices and quantities. Supports depth parameter to control the number of price levels returned.

GET/api/trading/trades

Recent trade history with timestamps, prices, quantities, and trade direction (buy/sell). Supports pagination via cursor.

GET/api/trading/chart

OHLCV (Open, High, Low, Close, Volume) candlestick data for charting. Supports 1m, 5m, 15m, 1h, 4h, 1d intervals.

GET/api/bonding-curve/status

Current bonding curve state: supply minted, current price, curve progress percentage, and graduation threshold.

GET/api/bonding-curve/quote

Get a price quote for buying or selling a specific quantity of tokens through the bonding curve. Returns estimated price impact and slippage.

4

Make Your First API Call

Here's a complete TypeScript example that fetches market data and displays token prices:

typescript
// Fetch all market data
async function getMarketData() {
  const res = await fetch('https://ipx.exchange/api/trading/market', {
    headers: {
      'Authorization': `Bearer ${process.env.IPX_API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  if (!res.ok) {
    throw new Error(`API error: ${res.status} ${res.statusText}`);
  }

  const { data } = await res.json();
  return data;
}

// Fetch order book for a specific token
async function getOrderBook(tokenAddress: string, depth = 20) {
  const params = new URLSearchParams({
    token: tokenAddress,
    depth: depth.toString(),
  });

  const res = await fetch(
    `https://ipx.exchange/api/trading/orderbook?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.IPX_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );

  if (!res.ok) {
    throw new Error(`API error: ${res.status} ${res.statusText}`);
  }

  const { data } = await res.json();
  return data; // { bids: [...], asks: [...] }
}

// Get a bonding curve quote
async function getBondingCurveQuote(
  tokenAddress: string,
  amount: string,
  side: 'buy' | 'sell'
) {
  const params = new URLSearchParams({
    token: tokenAddress,
    amount,
    side,
  });

  const res = await fetch(
    `https://ipx.exchange/api/bonding-curve/quote?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.IPX_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );

  if (!res.ok) {
    throw new Error(`API error: ${res.status} ${res.statusText}`);
  }

  const { data } = await res.json();
  return data;
  // { estimatedPrice, priceImpact, slippage, totalCost }
}
5

Understand Rate Limiting

The IPX API enforces rate limits to ensure fair usage and platform stability:

TierLimitWindow
Standard100 requestsPer minute
Market Data300 requestsPer minute
Trading30 requestsPer minute

Rate limit info is included in response headers:

text
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711036800

When you exceed the limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

6

Set Up Webhooks

Instead of polling, receive real-time notifications when events occur. Configure webhooks in Settings → Developer → Webhooks.

trade.executed

Fires when a trade is executed on any of your watched tokens

token.graduated

Fires when a token graduates from the bonding curve to the DEX

price.alert

Fires when a token price crosses your configured threshold

order.filled

Fires when one of your open orders is filled (partially or fully)

revenue.distributed

Fires when a project distributes revenue to token holders

Your webhook endpoint receives a POST request with a JSON payload:

typescript
// Example webhook handler (Next.js API route)
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('X-IPX-Signature');

  // Verify webhook signature
  const expectedSig = crypto
    .createHmac('sha256', process.env.IPX_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex');

  if (signature !== expectedSig) {
    return NextResponse.json(
      { error: 'Invalid signature' },
      { status: 401 }
    );
  }

  const event = JSON.parse(body);

  switch (event.type) {
    case 'trade.executed':
      console.log('Trade:', event.data);
      break;
    case 'token.graduated':
      console.log('Graduated:', event.data.tokenAddress);
      break;
    // Handle other events...
  }

  return NextResponse.json({ received: true });
}
7

Handle Errors Gracefully

The API uses standard HTTP status codes. Every error response includes a structured JSON body:

json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough USDC to complete this trade",
    "details": {
      "required": "150.00",
      "available": "42.50"
    }
  }
}

Common Error Codes

StatusCodeMeaning
400INVALID_PARAMSMissing or invalid query parameters
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENAPI key lacks permission for this endpoint
404NOT_FOUNDToken or resource not found
429RATE_LIMITEDToo many requests — back off and retry
500INTERNAL_ERRORServer error — retry with exponential backoff
8

SDK & Community Resources

Accelerate development with official and community resources:

TypeScript/JavaScript SDK

Official SDK with full type definitions, auto-retry, and WebSocket support.

npm install @ipx/sdk

API Reference Docs

Complete API reference with interactive request builder and example responses.

https://docs.ipx.exchange/api

Community Discord

Join the #developers channel for support, code sharing, and integration ideas.

discord.gg/ipx-developers

Best Practices

Cache Aggressively

Market data and order books change frequently, but you don't need millisecond freshness for most use cases. Cache responses for 5–15 seconds to reduce API calls and stay within rate limits.

Implement Retry Logic

Use exponential backoff for failed requests (1s, 2s, 4s, 8s, max 30s). Always check the Retry-After header on 429 responses. Never retry 400-level errors (except 429) — they indicate client issues.

Rotate API Keys Regularly

Generate new API keys every 90 days. Use separate keys for development and production. If a key is compromised, revoke it immediately from Settings → Developer.

Least Privilege Permissions

Only grant the permissions your integration actually needs. A portfolio tracker only needs Read access — don't give it Trade permissions. This limits damage if the key is leaked.

Handle Pagination

List endpoints return paginated results. Always check for a 'nextCursor' field and loop until it's null to get all results. Default page size is 50; max is 200.

Use Webhooks Over Polling

For real-time data needs, webhooks are far more efficient than polling. They eliminate wasted requests, reduce latency, and won't eat into your rate limit budget.

Troubleshooting

401 Unauthorized — Invalid API Key

Problem: Every request returns a 401 error even though you've included an API key.

Solution:

Check the following:

  • Verify the header format is exactly Authorization: Bearer YOUR_KEY (note the space after "Bearer")
  • Ensure there are no extra whitespace characters or newlines in the key
  • Check that the key hasn't been revoked in Settings → Developer
  • If using environment variables, verify they're loaded correctly (e.g., console.log(process.env.IPX_API_KEY?.length))
  • Generate a new key and test with it to rule out a corrupted key

429 Too Many Requests — Rate Limited

Problem: You're hitting rate limits and requests are being rejected.

Solution:

Solutions to reduce your request rate:

  • Implement local caching — don't fetch the same data multiple times within 5 seconds
  • Use the X-RateLimit-Remaining header to preemptively slow down before hitting the limit
  • Batch related queries where possible (e.g., use market data endpoint once instead of querying individual tokens)
  • Switch to webhooks for real-time data instead of polling
  • Respect the Retry-After header value before retrying

CORS Errors in Browser

Problem: Requests from your frontend JavaScript fail with CORS errors.

Solution:

This is expected behavior:

  • The IPX API is not designed for direct browser calls — this protects your API key from exposure in client-side code
  • Create a server-side proxy: your frontend calls your own API endpoint, which calls IPX
  • In Next.js, use API routes (/api/proxy/market) to forward requests
  • Store the API key in your server environment, never in frontend code or .env files that get bundled
  • Alternatively, use the official SDK which handles this pattern automatically

Webhook Not Receiving Events

Problem: You've configured a webhook URL but events aren't arriving at your endpoint.

Solution:

Debug your webhook setup:

  • Verify your endpoint is publicly accessible (not localhost) — use ngrok for local development
  • Ensure your endpoint returns a 2xx status code within 10 seconds — IPX retries 3 times on timeout
  • Check the webhook delivery logs in Settings → Developer → Webhooks → Delivery History
  • Verify the webhook is subscribed to the correct event types
  • Test with the "Send Test Event" button on the webhook configuration page
  • Check that your endpoint correctly handles POST requests with JSON body (not form data)

Stale or Delayed Data

Problem: API responses show prices or data that seem outdated.

Solution:

Considerations:

  • Market data has a natural propagation delay of 1–3 seconds from on-chain execution to API availability
  • If using caching, check your cache TTL isn't set too high for your use case
  • Verify you're not hitting a CDN-cached response — add a cache-busting parameter if needed
  • For time-critical applications, use WebSocket connections (available via the SDK) instead of REST polling
  • Check the X-Data-Timestamp response header to see when the data was generated

Related Guides

Ready to Build?

Check out the full API reference or join the developer community