Quickstart

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

All transaction endpoints return unsigned transactions. Your app is responsible for signing with the user’s wallet and submitting to the Solana network.

Standard Pools

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

Quote a buy

Before buying, get a quote to see how many tokens you’ll receive for a given SOL amount.

curl

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:

{
  "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
}

Build the buy transaction

Pass the full quote response to build a transaction.

curl

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:

{
  "tx": "Base64EncodedTransaction..."
}

Sign and submit

Decode the Base64 transaction, sign it with the payer’s wallet, and submit to Solana.

TypeScript

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

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();

Quote and sell

Selling follows the same pattern — quote first, then build the transaction.

curl

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.

Pro Pools

Pro Pools let you bring any existing SPL token onto Heaven’s AMM. See Pro Pools for a full overview.

Create a pro pool

Provide your existing token mint, initial liquidity amounts, and optional creator fee/feature configuration.

curl

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:

{
  "tx": "Base64EncodedTransaction...",
  "pool": "POOL_STATE_ADDRESS"
}

Save the pool address from the response — you’ll need it for all future interactions with this pool.

Buy tokens in a pro pool

Pro pool buys require two calls: quote, then build the transaction. Both need the pool address.

curl

# 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"
  }'

curl

# 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
  }'

Sell tokens in a pro pool

Same two-step flow as buying.

curl

# 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.

Deposit liquidity

Deposit tokens and SOL to earn LP tokens and trading fees.

curl

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.

Check LP balance

Query your LP position at any time.

curl

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:

{
  "lp_token_balance": 50000000,
  "reward_debt": 0,
  "pending_fees": 12345,
  "lp_position_address": "LP_POSITION_PDA",
  "exists": true
}

Manage pool (creator only)

As the pool creator, you can toggle features and update fees.

Toggle swap off

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
  }'

Set creator fee brackets

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

Data endpoints

Fetch pool information without building transactions.

Get pool info

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

Get protocol config

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 for all endpoints and parameters
Learn about Pro Pools for custom pool configuration

Getting started

About heaven

About $LIGHT

Developers

Brand

Security

Standard Pools

Pro Pools

Data endpoints

Next steps

​Standard Pools

​Pro Pools

​Data endpoints

​Next steps

Standard Pools

Pro Pools

Data endpoints

Next steps