> ## Documentation Index
> Fetch the complete documentation index at: https://blitzz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Blitzz API Documentation

> A fast API for trading and market data for tokens on Pump Fun and Pump AMM.

## Overview

Blitzz is a simple yet lightning-fast API for trading and market data tokens on Pump Fun and Pump AMM. Use it to build transactions, send them, fetch token metadata, and stream live human readable events.

## Base URLs

**HTTP Base URL:** `https://api.blitzz.fun`

**WebSocket URL:** `wss://api.blitzz.fun/ws`

<Warning>
  **ONLY WSOL PAIRS:** At the moment, the API only supports tokens whose Quote token is WSOL (pump-amm). Support for other pairs will be added in the future. We are NOT responsible for any issues caused when trading a non WSOL pair.
</Warning>

## Health Endpoint

**Method:** `GET`

**Path:** `/health`

**Purpose:** Warm up the connection to remove TCP handshake delay before trading.

**Response:** `200 OK` (empty body)

```bash theme={null}
curl -i https://api.blitzz.fun/health
```

## Authentication

No API key is required to use the Blitzz API. However, per-IP rate limits apply to each endpoint.

## Conventions

* **Public Keys:** All public keys are represented as base58 strings.
* **Amounts:**
  * `amount` for buy or create is specified in lamports (1 SOL = 1,000,000,000 lamports).
  * `amount` for sell is specified in token base units (6 decimals).
* **Slippage:** `slippage_pct` is a percentage (e.g., 0.5 means 0.5%).
* **Priority Fee:** `prioFee` is the priority fee in SOL (e.g., 0.0005).
* **Pool:** `pool` must be one of "pump", "pump-amm", or "auto".
* **Errors:** Errors are returned in a standard JSON format.

## Local Trade Endpoint

Build an unsigned transaction that you can sign with your own wallet and send through your preferred RPC endpoint or Transaction Processor (e.g., Astralane).

**Method:** `POST`

**Path:** `/local-trade`

**Rate Limit:** 5 requests/second per IP

### Request Body

<ParamField body="type" type="string" required>
  The type of transaction to build. Must be one of: `"buy"`, `"sell"`, `"create"`, or `"claimCreatorFees"`.
</ParamField>

<ParamField body="pool" type="string" required>
  The liquidity pool to use for the trade. Must be one of: `"pump"`, `"pump-amm"`, or `"auto"`.
</ParamField>

<ParamField body="mint" type="string">
  The base58 mint address of the token (required for `buy` and `sell`).
</ParamField>

<ParamField body="payer" type="string">
  The base58 public key of the fee payer (required for `buy`, `sell`, and `create`).
</ParamField>

<ParamField body="creator" type="string">
  The base58 public key of the token creator (required for `claimCreatorFees`).
</ParamField>

<ParamField body="amount" type="number">
  * For `buy`/`create`: The amount of SOL in lamports.
  * For `sell`: The amount of tokens in base units (6 decimals).
  * Not required for `claimCreatorFees`.
</ParamField>

<ParamField body="slippage_pct" type="number">
  The slippage tolerance as a percentage (e.g., `0.5` for 0.5%). Required for `buy`, `sell`, and `create`.
</ParamField>

<ParamField body="prioFee" type="number" required>
  The priority fee in SOL (e.g., `0.0005`).
</ParamField>

<ParamField body="metadata" type="object">
  Required for `type="create"`. Contains `name`, `symbol`, and `uri`.
</ParamField>

<ParamField body="transferConfig" type="object">
  Optional configuration to transfer SOL in the same transaction. Contains `pubkey` (base58) and `lamports` (string).
</ParamField>

### Response

<ResponseField name="tx" type="string">
  Base64-encoded unsigned transaction.
</ResponseField>

<ResponseField name="error" type="string">
  Descriptive error message (only present on error).
</ResponseField>

### Examples

<CodeGroup>
  ```bash Buy on Pump Fun theme={null}
  curl -X POST https://api.blitzz.fun/local-trade \
    -H 'content-type: application/json' \
    -d '{
      "type": "buy",
      "pool": "pump",
      "mint": "MINT_ADDRESS",
      "payer": "PAYER_ADDRESS",
      "amount": 10000000,
      "slippage_pct": 0.5,
      "prioFee": 0.0005
    }'
  ```

  ```bash Sell on Pump AMM theme={null}
  curl -X POST https://api.blitzz.fun/local-trade \
    -H 'content-type: application/json' \
    -d '{
      "type": "sell",
      "pool": "pump-amm",
      "mint": "MINT_ADDRESS",
      "payer": "PAYER_ADDRESS",
      "amount": 250000000,
      "slippage_pct": 0.5,
      "prioFee": 0.0005
    }'
  ```

  ```bash Create a Token theme={null}
  curl -X POST https://api.blitzz.fun/local-trade \
    -H 'content-type: application/json' \
    -d '{
      "type": "create",
      "pool": "pump",
      "payer": "PAYER_ADDRESS",
      "amount": 10000000,
      "slippage_pct": 0.5,
      "prioFee": 0.0005,
      "metadata": {
        "name": "My Token",
        "symbol": "MYT",
        "uri": "https://example.com/meta.json"
      }
    }'
  ```

  ```bash Claim Creator Fees theme={null}
  curl -X POST https://api.blitzz.fun/local-trade \
    -H 'content-type: application/json' \
    -d '{
      "type": "claimCreatorFees",
      "creator": "D89hHJT5Aqyx1trP6EnGY9jJUB3whgnq3aUvvCqedvzf",
      "prioFee": 0.005,
      "pool": "pump"
    }'
  ```
</CodeGroup>

<Check>
  The response contains a base64-encoded unsigned transaction. Decode it, sign it with your wallet, and send it using your RPC provider.
</Check>

## Blitzz Mode Endpoint

Build, sign, and send a transaction in a single API call. The API signs with the provided private key and sends the transaction through our dedicated nodes for the fastest landing times.

**Method:** `POST`

**Path:** `/blitzz`

**Rate Limit:** 3 requests/second per IP

### Request Body

Includes all fields from `/local-trade`, plus:

<ParamField body="privateKey" type="string" required>
  The base58 private key used to sign the transaction and pay fees.
</ParamField>

<Warning>
  **Handle with care:** Never expose your private keys in client-side code or public repositories. For a fully self-custodial flow, use the `/local-trade` endpoint.
</Warning>

### Response

<ResponseField name="status" type="string">
  Transaction status (e.g., `"success"`).
</ResponseField>

<ResponseField name="signature" type="string">
  The transaction signature.
</ResponseField>

<ResponseField name="error" type="string">
  Descriptive error message (only present on error).
</ResponseField>

### Examples

<CodeGroup>
  ```bash Auto-Buy theme={null}
  curl -X POST https://api.blitzz.fun/blitzz \
    -H 'content-type: application/json' \
    -d '{
      "type": "buy",
      "pool": "auto",
      "mint": "MINT_ADDRESS",
      "amount": 10000000,
      "slippage_pct": 0.5,
      "prioFee": 0.0005,
      "privateKey": "YOUR_PRIVATE_KEY"
    }'
  ```

  ```bash Claim Creator Fees theme={null}
  curl -X POST https://api.blitzz.fun/blitzz \
    -H 'content-type: application/json' \
    -d '{
      "type": "claimCreatorFees",
      "privateKey": "YOUR_PRIVATE_KEY",
      "prioFee": 0.005,
      "pool": "pump"
    }'
  ```
</CodeGroup>

## Metadata Endpoint

Fetch on-chain metadata for one or more tokens.

**Method:** `POST`

**Path:** `/metadata`

**Rate Limit:** 1 request/second per IP

**Limit:** Up to 10 mints per request

### Request Body

<ParamField body="mints" type="array" required>
  An array of 1 to 10 base58 mint addresses.
</ParamField>

### Response

<ResponseField name="results" type="array">
  Array of metadata objects for successfully fetched tokens.
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error objects for tokens that could not be fetched.
</ResponseField>

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.blitzz.fun/metadata \
    -H 'content-type: application/json' \
    -d '{
      "mints": [
        "MINT_ADDRESS_1",
        "MINT_ADDRESS_2"
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "results": [
      {
        "mint": "MINT_ADDRESS_1",
        "metadata_pda": "META_PDA",
        "update_authority": "UPDATE_AUTH",
        "data": {
          "name": "My Token",
          "symbol": "MYT",
          "uri": "https://...",
          "seller_fee_basis_points": 500,
          "creators": [
            { "address": "CREATOR1", "verified": true, "share": 100 }
          ]
        },
        "primary_sale_happened": true,
        "is_mutable": false,
        "edition_nonce": 255,
        "token_standard": 4,
        "collection": { "verified": true, "key": "COLLECTION_MINT" },
        "uses": { "use_method": 2, "remaining": 0, "total": 0 }
      }
    ],
    "errors": [
      { "mint": "MINT_ADDRESS_2", "error": "account not found" }
    ]
  }
  ```
</CodeGroup>

## Data WebSocket

Stream real-time events, including trades, token creations, and migrations.

**URL:** `wss://api.blitzz.fun/ws`

**Path:** `/`

**Limits:**

* Max 2 connections per IP.
* You must subscribe to at least one filter within 10 seconds of connecting.
* Max Limit of 50 Pubkeys on the Mint and Account filter.

### Subscribing to Events

Send a JSON message to the WebSocket to subscribe to events. You can filter by mint, account, or event type.

<AccordionGroup>
  <Accordion title="Subscribe to mints">
    ```json theme={null}
    { "method": "subscribeFilterMint", "pubkeys": ["MINT1", "MINT2"] }
    ```
  </Accordion>

  <Accordion title="Subscribe to accounts (trader/creator)">
    ```json theme={null}
    { "method": "subscribeFilterAccount", "pubkeys": ["ACCOUNT1"] }
    ```
  </Accordion>

  <Accordion title="Subscribe to new token creations">
    ```json theme={null}
    { "method": "subscribeNewCreation" }
    ```
  </Accordion>

  <Accordion title="Subscribe to migration events">
    ```json theme={null}
    { "method": "subscribeMigrations" }
    ```
  </Accordion>
</AccordionGroup>

### Unsubscribing from Events

<AccordionGroup>
  <Accordion title="Unsubscribe from mints">
    ```json theme={null}
    { "method": "unsubscribeFilterMint", "pubkeys": ["MINT1"] }
    ```
  </Accordion>

  <Accordion title="Unsubscribe from accounts">
    ```json theme={null}
    { "method": "unsubscribeFilterAccount", "pubkeys": ["ACCOUNT1"] }
    ```
  </Accordion>

  <Accordion title="Unsubscribe from new creations">
    ```json theme={null}
    { "method": "unsubscribeNewCreation" }
    ```
  </Accordion>

  <Accordion title="Unsubscribe from migrations">
    ```json theme={null}
    { "method": "unsubscribeMigrations" }
    ```
  </Accordion>
</AccordionGroup>

### Event Examples

<CodeGroup>
  ```json Trade (Pump Fun) theme={null}
  {
    "signature": "SIG",
    "mint": "MINT",
    "traderPublicKey": "TRADER",
    "txType": "buy",
    "tokenAmount": 123.456,
    "solAmount": 0.123,
    "virtualSolReserves": 123456789,
    "virtualTokenReserves": 987654321,
    "pool": "pump"
  }
  ```

  ```json Trade (Pump AMM) theme={null}
  {
    "signature": "SIG",
    "mint": "MINT",
    "traderPublicKey": "TRADER",
    "txType": "sell",
    "tokenAmount": 10.0,
    "solAmount": 0.05,
    "poolBaseTokenReserves": 100000000,
    "poolQuoteTokenReserves": 500000000,
    "poolAccount": "POOL",
    "pool": "pump-amm"
  }
  ```

  ```json Create (Pump Fun) theme={null}
  {
    "signature": "SIG",
    "mint": "MINT",
    "creator": "CREATOR",
    "txType": "create",
    "initialBuy": 100.0,
    "solAmount": 0.5,
    "bondingCurve": "BC_PDA",
    "name": "My Token",
    "symbol": "MYT",
    "uri": "https://...",
    "pool": "pump"
  }
  ```

  ```json Migrate (Pump Fun) theme={null}
  {
    "signature": "SIG",
    "txType": "migrate",
    "mint": "MINT",
    "lp_mint": "LP_MINT",
    "poolAccount": "POOL",
    "pool": "pump"
  }
  ```
</CodeGroup>

## Errors and Limits

### Common HTTP Errors

* **400 Bad Request:** Invalid input (e.g., bad pubkey, amount \< 0).
* **404 Not Found:** Item not found (e.g., token or pool does not exist).
* **429 Too Many Requests:** Rate limit exceeded.
* **500 Internal Server Error / 502 Bad Gateway:** Server or upstream error.
* **503 Service Unavailable:** Blockhash is temporarily unavailable.
* **504 Gateway Timeout:** Timed out waiting for transaction confirmation on `/blitzz`.

### Rate Limits

<CardGroup cols={2}>
  <Card title="/local-trade" icon="arrow-right-arrow-left">
    5 requests/second per IP
  </Card>

  <Card title="/blitzz" icon="bolt">
    3 requests/second per IP
  </Card>

  <Card title="/metadata" icon="tags">
    1 request/second per IP (10 mints max)
  </Card>

  <Card title="WebSocket" icon="circle-nodes">
    2 connections per IP
  </Card>
</CardGroup>

## Best Practices

<Tip>
  * **Slippage:** Keep slippage reasonable to avoid failed trades.
  * **Pool Selection:**
    * `"pump"`: For bonding-curve trades.
    * `"pump-amm"`: For AMM trades.
    * `"auto"`: Let the API automatically choose the pool. This can be slower sometimes.
  * **Security:** For `/blitzz`, use a dedicated hot wallet with limited funds incase of any leak. For maximum security and control, use `/local-trade` to sign transactions locally.
  * **Warmup The Connection:** Use the /health endpoint to keep the connection open with the server and have lower latency to the server.
</Tip>