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

# Quickstart

> Quickstart guide for integrating with Heaven using the REST API. No SDK required — just HTTP requests.

Heaven's REST API lets you build transactions server-side and sign them client-side. All endpoints return Base64-encoded Solana transactions that you decode, sign, and submit.

**Base URL:** `https://tx.api.heaven.xyz`

<Info>
  All transaction endpoints return unsigned transactions. Your app is responsible for signing with the user's wallet and submitting to the Solana network.
</Info>

## Standard Pools

Standard pools use Heaven's one-click launch flow — create a new token and pool in a single transaction.

<Steps>
  <Step title="Quote a buy">
    Before buying, get a quote to see how many tokens you'll receive for a given SOL amount.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/quote/buy \
      -H "Content-Type: application/json" \
      -d '{
        "config_version": 1,
        "mint": "88aUGeGXFNaEyzL48fkzSPWUPhJr3gWrMDD8EH8tCb1",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "max_sol_spend": 0.1,
        "slippage_bps": 50
      }'
    ```

    Response:

    ```json theme={null}
    {
      "config_version": 1,
      "mint": "88aUGeGXFNaEyzL48fkzSPWUPhJr3gWrMDD8EH8tCb1",
      "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
      "max_sol_spend": 0.1,
      "slippage_bps": 50,
      "amount_out": 1234567890,
      "amount_out_ui": 1234.56789,
      "minimum_out": 1228395551,
      "minimum_out_ui": 1228.395551,
      "fee": 100000,
      "fee_pct": 0.01
    }
    ```
  </Step>

  <Step title="Build the buy transaction">
    Pass the full quote response to build a transaction.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/tx/buy \
      -H "Content-Type: application/json" \
      -d '{
        "payer": "YOUR_WALLET_PUBKEY",
        "encoded_user_defined_event_data": "",
        "quote_response": { ... the full quote response ... },
        "compute_unit_limit": 400000,
        "compute_unit_price": 2000000
      }'
    ```

    Response:

    ```json theme={null}
    {
      "tx": "Base64EncodedTransaction..."
    }
    ```
  </Step>

  <Step title="Sign and submit">
    Decode the Base64 transaction, sign it with the payer's wallet, and submit to Solana.

    ```typescript TypeScript theme={null}
    import { VersionedTransaction } from "@solana/web3.js";
    import bs58 from "bs58";

    // Decode the transaction
    const txBytes = Buffer.from(response.tx, "base64");
    const tx = VersionedTransaction.deserialize(txBytes);

    // Sign with the user's wallet
    tx.sign([payerKeypair]);

    // Submit
    const signature = await connection.sendTransaction(tx);
    await connection.confirmTransaction(signature);
    ```

    ```rust Rust theme={null}
    use base64::prelude::*;
    use solana_sdk::transaction::VersionedTransaction;

    let tx_bytes = BASE64_STANDARD.decode(&response.tx).unwrap();
    let mut tx: VersionedTransaction = bincode::deserialize(&tx_bytes).unwrap();

    // Update blockhash and sign
    tx.message.set_recent_blockhash(rpc_client.get_latest_blockhash().await.unwrap());
    tx.signatures[0] = payer.sign_message(&tx.message.serialize());

    // Submit
    rpc_client.send_and_confirm_transaction(&tx).await.unwrap();
    ```
  </Step>

  <Step title="Quote and sell">
    Selling follows the same pattern — quote first, then build the transaction.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/quote/sell \
      -H "Content-Type: application/json" \
      -d '{
        "config_version": 1,
        "mint": "88aUGeGXFNaEyzL48fkzSPWUPhJr3gWrMDD8EH8tCb1",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "amount_in_ui": 1234.56789,
        "slippage_bps": 50
      }'
    ```

    Then pass the response to `/tx/sell` to build the transaction.
  </Step>
</Steps>

## Pro Pools

Pro Pools let you bring any existing SPL token onto Heaven's AMM. See [Pro Pools](/pro-pools) for a full overview.

<Steps>
  <Step title="Create a pro pool">
    Provide your existing token mint, initial liquidity amounts, and optional creator fee/feature configuration.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/tx/pro/create \
      -H "Content-Type: application/json" \
      -d '{
        "payer": "YOUR_WALLET_PUBKEY",
        "creator": "YOUR_WALLET_PUBKEY",
        "encoded_user_defined_event_data": "",
        "config_version": 3,
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "mint": "YOUR_TOKEN_MINT_ADDRESS",
        "initial_token_a_amount": 500000000000,
        "initial_token_b_amount": 5000000000,
        "lut_address": "YOUR_LUT_ADDRESS",
        "features": {
          "enable_swap": true,
          "enable_deposit_liquidity": true,
          "enable_withdraw_liquidity": true,
          "enable_sandwich_resistant_mode": true
        },
        "creator_trading_fee": [
          { "market_cap_upper_bound": 100000000000, "buy_fee_bps": 200, "sell_fee_bps": 200 },
          { "market_cap_upper_bound": 9223372036854775807, "buy_fee_bps": 100, "sell_fee_bps": 100 }
        ],
        "creator_slot_trading_fee": {
          "brackets": [
            { "buy_fee_bps": 5000, "sell_fee_bps": 5000, "slot_offset_upperbound": 5 },
            { "buy_fee_bps": 1000, "sell_fee_bps": 1000, "slot_offset_upperbound": 15 }
          ],
          "max_slot_offset": 15,
          "max_fee_bps": 5000,
          "enabled": true
        }
      }'
    ```

    Response:

    ```json theme={null}
    {
      "tx": "Base64EncodedTransaction...",
      "pool": "POOL_STATE_ADDRESS"
    }
    ```

    <Info>
      Save the `pool` address from the response — you'll need it for all future interactions with this pool.
    </Info>
  </Step>

  <Step title="Buy tokens in a pro pool">
    Pro pool buys require two calls: quote, then build the transaction. Both need the `pool` address.

    ```bash curl icon=terminal theme={null}
    # Step 1: Get a quote
    curl -X POST https://tx.api.heaven.xyz/quote/pro/buy \
      -H "Content-Type: application/json" \
      -d '{
        "config_version": 3,
        "mint": "YOUR_TOKEN_MINT_ADDRESS",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "max_sol_spend": 1.0,
        "slippage_bps": 50,
        "pool": "POOL_STATE_ADDRESS"
      }'
    ```

    ```bash curl icon=terminal theme={null}
    # Step 2: Build the transaction
    curl -X POST https://tx.api.heaven.xyz/tx/pro/buy \
      -H "Content-Type: application/json" \
      -d '{
        "payer": "YOUR_WALLET_PUBKEY",
        "encoded_user_defined_event_data": "",
        "quote_response": { ... the full quote response ... },
        "pool": "POOL_STATE_ADDRESS",
        "compute_unit_limit": 400000,
        "compute_unit_price": 2000000
      }'
    ```
  </Step>

  <Step title="Sell tokens in a pro pool">
    Same two-step flow as buying.

    ```bash curl icon=terminal theme={null}
    # Step 1: Get a quote
    curl -X POST https://tx.api.heaven.xyz/quote/pro/sell \
      -H "Content-Type: application/json" \
      -d '{
        "config_version": 3,
        "mint": "YOUR_TOKEN_MINT_ADDRESS",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "amount_in_ui": 1000.0,
        "slippage_bps": 50,
        "pool": "POOL_STATE_ADDRESS"
      }'
    ```

    Then pass the response to `/tx/pro/sell`.
  </Step>

  <Step title="Deposit liquidity">
    Deposit tokens and SOL to earn LP tokens and trading fees.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/tx/pro/add-liquidity \
      -H "Content-Type: application/json" \
      -d '{
        "payer": "YOUR_WALLET_PUBKEY",
        "mint": "YOUR_TOKEN_MINT_ADDRESS",
        "config_version": 3,
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "pool": "POOL_STATE_ADDRESS",
        "max_token_a": 100000000000,
        "max_token_b": 1000000000,
        "min_lp_tokens": 0,
        "compute_unit_limit": 400000,
        "compute_unit_price": 2000000
      }'
    ```

    The actual deposited amounts will be proportional to the pool's current ratio. Set `min_lp_tokens` above 0 to protect against slippage.
  </Step>

  <Step title="Check LP balance">
    Query your LP position at any time.

    ```bash curl icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/data/lp-balance \
      -H "Content-Type: application/json" \
      -d '{
        "pool": "POOL_STATE_ADDRESS",
        "user": "YOUR_WALLET_PUBKEY",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "lp_token_balance": 50000000,
      "reward_debt": 0,
      "pending_fees": 12345,
      "lp_position_address": "LP_POSITION_PDA",
      "exists": true
    }
    ```
  </Step>

  <Step title="Manage pool (creator only)">
    As the pool creator, you can toggle features and update fees.

    ```bash Toggle swap off icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/tx/pro/toggle-swap \
      -H "Content-Type: application/json" \
      -d '{
        "pool": "POOL_STATE_ADDRESS",
        "payer": "CREATOR_WALLET_PUBKEY",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "enabled": false,
        "compute_unit_limit": 200000,
        "compute_unit_price": 2000000
      }'
    ```

    ```bash Set creator fee brackets icon=terminal theme={null}
    curl -X POST https://tx.api.heaven.xyz/tx/pro/set-market-cap-creator-fee \
      -H "Content-Type: application/json" \
      -d '{
        "pool": "POOL_STATE_ADDRESS",
        "payer": "CREATOR_WALLET_PUBKEY",
        "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o",
        "brackets": [
          { "market_cap_upper_bound": 100000000000, "buy_fee_bps": 200, "sell_fee_bps": 200 },
          { "market_cap_upper_bound": 9223372036854775807, "buy_fee_bps": 50, "sell_fee_bps": 50 }
        ],
        "compute_unit_limit": 200000,
        "compute_unit_price": 2000000
      }'
    ```

    Other creator endpoints: `/tx/pro/toggle-deposit`, `/tx/pro/toggle-withdraw`, `/tx/pro/set-slot-creator-fee`, `/tx/pro/update-creator-fee-receiver`
  </Step>
</Steps>

## Data endpoints

Fetch pool information without building transactions.

```bash Get pool info icon=terminal theme={null}
curl -X POST https://tx.api.heaven.xyz/data/pool-info \
  -H "Content-Type: application/json" \
  -d '{
    "mint": "88aUGeGXFNaEyzL48fkzSPWUPhJr3gWrMDD8EH8tCb1",
    "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o"
  }'
```

```bash Get protocol config icon=terminal theme={null}
curl -X POST https://tx.api.heaven.xyz/data/protocol-config-state \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "program_id": "HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o"
  }'
```

## Next steps

* See the full [API reference](/api-reference) for all endpoints and parameters
* Learn about [Pro Pools](/pro-pools) for custom pool configuration