Lightning API

The Lightning API is our HTTPS-based trading API designed for quick integration. Send a request and we handle everything: transaction building, signing, and broadcasting.

Overview

Base URL: https://api.turnpike.dev

Authentication: Bearer token in Authorization header

Rate Limits:

• Standard: 100 requests/minute

• Premium: 1,000 requests/minute

Endpoints

Buy Token

Execute a buy order for a specific token.

Endpoint: POST /trade/buy

Request Body:

Parameter	Type	Required	Description
publicKey	string	Yes	Your Solana wallet public key (base58 format)
mint	string	Yes	Token mint address to purchase
amount	number	Yes	Amount of SOL to spend (min: 0.001, max: 100)
slippage	number	No	Maximum slippage percentage (default: 10, range: 0.1-50)
priorityFee	number	No	Priority fee in SOL (default: auto, range: 0.00001-0.01)

Example Request:

curl -X POST https://api.turnpike.dev/trade/buy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "publicKey": "7BgBvyjrZX8YTqjkKrfbSx9X8QP4NDaP1hj4VKMjqA5s",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": 0.01,
    "slippage": 10,
    "priorityFee": 0.0001
  }'

Success Response (200):

{
  "success": true,
  "signature": "5j7sK8K2YaFvS2hE3YgY4zRtV3pGq1Y7zxP8c9X3Qa6",
  "amount": 0.01,
  "tokensReceived": 1000000,
  "effectivePrice": 0.00001,
  "slippageUsed": 2.3,
  "priorityFeeUsed": 0.0001,
  "blockHeight": 123456789,
  "timestamp": 1697234567890,
  "estimatedConfirmation": "2-5 seconds"
}

---

Sell Token

Execute a sell order for tokens you own. Supports both token amount and percentage-based selling.

Endpoint: POST /trade/sell

Request Body:

Parameter	Type	Required	Description
publicKey	string	Yes	Your Solana wallet public key
mint	string	Yes	Token mint address to sell
amount	number | string	Yes	Token amount to sell or percentage ("50%", "100%")
slippage	number	No	Maximum slippage percentage (default: 10)
priorityFee	number	No	Priority fee in SOL (default: auto)
sellAll	boolean	No	If true, sells entire balance (default: false)

Example Request:

curl -X POST https://api.turnpike.dev/trade/sell \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "publicKey": "7BgBvyjrZX8YTqjkKrfbSx9X8QP4NDaP1hj4VKMjqA5s",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "50%",
    "slippage": 15,
    "priorityFee": 0.0001
  }'

Success Response (200):

{
  "success": true,
  "signature": "3k9mN7PqRtV8sW2xY1zC4aB6nH5jL8fG9eD3cF2qA7s",
  "tokensSold": 500000,
  "solReceived": 5.234,
  "effectivePrice": 0.00001046,
  "slippageUsed": 3.1,
  "priorityFeeUsed": 0.0001,
  "timestamp": 1697234567890
}

---

Get Token Info

Retrieve detailed information about a specific token.

Endpoint: GET /token/info/{mint}

Parameters:

Parameter	Type	Required	Description
mint	string	Yes	Token mint address (path parameter)

Example Request:

curl -X GET https://api.turnpike.dev/token/info/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response (200):

{
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "symbol": "USDC",
  "name": "USD Coin",
  "decimals": 6,
  "price": 1.0,
  "marketCap": 25000000000,
  "liquidityUsd": 890000,
  "volume24h": 2400000,
  "priceChange24h": 0.1,
  "holders": 3421,
  "isActive": true
}

---

Get Portfolio

Get all token holdings for a specific wallet address.

Endpoint: GET /portfolio/{publicKey}

Parameters:

Parameter	Type	Required	Description
publicKey	string	Yes	Wallet public key (path parameter)

Example Request:

curl -X GET https://api.turnpike.dev/portfolio/7BgBvyjrZX8YTqjkKrfbSx9X8QP4NDaP1hj4VKMjqA5s \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response (200):

{
  "publicKey": "7BgBvyjrZX8YTqjkKrfbSx9X8QP4NDaP1hj4VKMjqA5s",
  "totalValueUsd": 1250.75,
  "solBalance": 5.234,
  "tokens": [
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "balance": 1000,
      "decimals": 6,
      "valueUsd": 1000.0,
      "price": 1.0
    }
  ]
}

Error Responses

All endpoints may return these common errors:

400 Bad Request

Invalid parameters:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid request parameters",
    "details": {
      "amount": "Must be between 0.001 and 100"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

429 Rate Limit

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "retryAfter": 30
  }
}

Common Error Codes

Code	Description	Solution
INSUFFICIENT_BALANCE	Not enough SOL for transaction + fees	Add more SOL to wallet
INVALID_MINT	Token mint address invalid or doesn't exist	Verify mint address
SLIPPAGE_EXCEEDED	Price moved beyond acceptable slippage	Increase slippage tolerance
RATE_LIMIT	Too many requests	Slow down requests

See Error Handling for complete error documentation.

Code Examples

JavaScript/TypeScript

const axios = require('axios');

async function buyToken(publicKey, mint, amount) {
  try {
    const response = await axios.post(
      'https://api.turnpike.dev/trade/buy',
      {
        publicKey,
        mint,
        amount,
        slippage: 10,
        priorityFee: 0.0001
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.TURNPIKE_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Trade successful:', response.data);
    return response.data;
  } catch (error) {
    console.error('Trade failed:', error.response?.data || error.message);
    throw error;
  }
}

Python

import requests
import os

def buy_token(public_key: str, mint: str, amount: float):
    url = 'https://api.turnpike.dev/trade/buy'
    headers = {
        'Authorization': f'Bearer {os.getenv("TURNPIKE_API_KEY")}',
        'Content-Type': 'application/json'
    }
    payload = {
        'publicKey': public_key,
        'mint': mint,
        'amount': amount,
        'slippage': 10,
        'priorityFee': 0.0001
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        print('Trade successful:', response.json())
        return response.json()
    except requests.exceptions.RequestException as e:
        print('Trade failed:', e)
        raise

Best Practices

1. Always Handle Errors: Implement robust error handling for all requests

2. Use Appropriate Slippage: Higher slippage for volatile tokens, lower for stablecoins

3. Monitor Transactions: Track signatures and verify confirmations

4. Respect Rate Limits: Implement backoff strategies

5. Secure API Keys: Never expose keys in client-side code

6. Test with Small Amounts: Validate integration with minimal SOL first

Next Steps

• Learn about Local Transaction API for full control

• Set up WebSocket streaming for real-time data

• View code examples for your language