diff --git a/.env.example b/.env.example index a0cd2770..90dfab5f 100644 --- a/.env.example +++ b/.env.example @@ -19,6 +19,8 @@ MAINNET_ENDPOINT=https://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_KEY # STELLIUM_API_KEY= # FLASHBLOCK_API_KEY= # NODE1_API_KEY= +# APEX_API_KEY= +# APEX_REGION=global # global|fra|ams|dub|lon|nyc|slc|sgp|tyo|sqq # ─── Trading Defaults (optional) ──────────────────────────── # TX_LANDING_MODE=concurrent # concurrent|race|random|sequential diff --git a/README.md b/README.md index ed5ecbbc..ef6febb8 100644 --- a/README.md +++ b/README.md @@ -664,7 +664,7 @@ await manager.stop(); ## TX Landing Providers -12 providers with concurrent, race, random, and sequential submission strategies: +13 providers with concurrent, race, random, and sequential submission strategies: | Provider | Env Var | |----------|---------| @@ -680,6 +680,7 @@ await manager.stop(); | Stellium | `STELLIUM_API_KEY` | | Flashblock | `FLASHBLOCK_API_KEY` | | Node1 | `NODE1_API_KEY` | +| OrbitFlare Apex | `APEX_API_KEY` (optional `APEX_REGION`, default `global`) | Set any provider's API key and it's automatically enabled. The orchestrator sends your transaction through all enabled providers simultaneously for the fastest possible landing. @@ -773,7 +774,7 @@ src/ ├── orchestrator.ts # Multi-provider concurrent submission ├── nonce-manager.ts # Durable nonce for dedup ├── tip-accounts.ts # Tip account registry - └── providers/ # 12 provider implementations + └── providers/ # 13 provider implementations ``` ## Discord diff --git a/docs/index.html b/docs/index.html index b4f44cf7..bda67b3d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,9 +4,9 @@ outsmart - Solana Trading CLI & SDK - + - + @@ -381,7 +381,7 @@
-
v2.0.0-alpha · 18 DEX adapters · Percolator perps · 12 TX providers
+
v2.0.0-alpha · 18 DEX adapters · Percolator perps · 13 TX providers

Trade every Solana DEX
from your terminal

One CLI and TypeScript SDK to buy, sell, LP, and create pools across every major Solana protocol. Built for traders, bots, and AI agents.

@@ -677,7 +677,7 @@

DEX Adapters

TX Landing Providers

-

12 providers running simultaneously. Set the API key and the provider auto-enables.

+

13 providers running simultaneously. Set the API key and the provider auto-enables.

JitoJITO_API_KEY
bloXrouteBLOXROUTE_AUTH_HEADER
@@ -691,6 +691,7 @@

TX Landing Providers

StelliumSTELLIUM_API_KEY
FlashblockFLASHBLOCK_API_KEY
Node1NODE1_API_KEY
+
OrbitFlare ApexAPEX_API_KEY
⚡ Concurrent @@ -775,7 +776,7 @@

Project Structure

send-rpc.ts # Simulation, backoff, dry-run landing/ orchestrator.ts # Multi-provider submission - providers/ # 12 provider implementations + providers/ # 13 provider implementations

Testing

diff --git a/src/cli.ts b/src/cli.ts index f767eb61..bc18ee8b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1483,6 +1483,8 @@ configCmd "STELLIUM_API_KEY", "FLASHBLOCK_API_KEY", "NODE1_API_KEY", + "APEX_API_KEY", + "APEX_REGION", "TX_LANDING_MODE", "TX_LANDING_PROVIDERS", "DEFAULT_TIP_SOL", @@ -1535,6 +1537,8 @@ SOLANA_RPC_URL=https://api.mainnet-beta.solana.com # STELLIUM_API_KEY= # FLASHBLOCK_API_KEY= # NODE1_API_KEY= +# APEX_API_KEY= +# APEX_REGION=global # global|fra|ams|dub|lon|nyc|slc|sgp|tyo|sqq # ─── TX Landing Strategy ─── # TX_LANDING_MODE=race # concurrent|race|random|sequential @@ -1641,6 +1645,8 @@ program "# STELLIUM_API_KEY=", "# FLASHBLOCK_API_KEY=", "# NODE1_API_KEY=", + "# APEX_API_KEY=", + "# APEX_REGION=global", "", "# ─── Trading Defaults (optional) ───", "# TX_LANDING_MODE=concurrent", diff --git a/src/transactions/landing/index.ts b/src/transactions/landing/index.ts index 6599b0de..c19676e2 100644 --- a/src/transactions/landing/index.ts +++ b/src/transactions/landing/index.ts @@ -55,3 +55,4 @@ export { createProvider as createFlashblockProvider } from "./providers/flashblo export { createProvider as createJitoProvider } from "./providers/jito"; export { createProvider as createNextblockProvider } from "./providers/nextblock"; export { createProvider as createSoyasProvider } from "./providers/soyas"; +export { createProvider as createApexProvider } from "./providers/apex"; diff --git a/src/transactions/landing/orchestrator.ts b/src/transactions/landing/orchestrator.ts index dac7febc..3c288c01 100644 --- a/src/transactions/landing/orchestrator.ts +++ b/src/transactions/landing/orchestrator.ts @@ -37,6 +37,7 @@ import { createProvider as createFlashblock } from "./providers/flashblock"; import { createProvider as createJito } from "./providers/jito"; import { createProvider as createNextblock } from "./providers/nextblock"; import { createProvider as createSoyas } from "./providers/soyas"; +import { createProvider as createApex } from "./providers/apex"; // --------------------------------------------------------------------------- // Provider registry @@ -55,12 +56,13 @@ const PROVIDER_FACTORIES: Record ILandingProvider> = { "jito": createJito, "nextblock": createNextblock, "soyas": createSoyas, + "apex": createApex, }; /** Default providers for concurrent snipe submission (matches source orchestrator) */ const DEFAULT_SNIPE_PROVIDERS = [ "zero-slot", "nozomi", "helius-sender", "astralane", - "stellium", "blockrazor", "flashblock", "node1", "soyas", + "stellium", "blockrazor", "flashblock", "node1", "soyas", "apex", ]; /** Default providers for random pick strategy */ diff --git a/src/transactions/landing/providers/apex.ts b/src/transactions/landing/providers/apex.ts new file mode 100644 index 00000000..4aea6c97 --- /dev/null +++ b/src/transactions/landing/providers/apex.ts @@ -0,0 +1,158 @@ +/** + * OrbitFlare Apex TX Landing Provider + * + * Submits transactions via Apex's HTTP JSON-RPC endpoint. Apex sends each + * transaction to the upcoming leaders over staked validator clients, Jito + * bundles and direct TPU at once; one tip covers all three paths. + * Uses sendTransaction with base64 encoding and the x-api-key header. + * + * Env: + * APEX_API_KEY — required; enables the provider + * APEX_REGION — global (default, nearest healthy endpoint) or + * fra|ams|dub|lon|nyc|slc|sgp|tyo|sqq + * APEX_URL — full endpoint URL; overrides APEX_REGION + * APEX_MEV_PROTECT — "true" to skip leaders on Apex's MEV blocklist + * + * Supports ping() to keep the HTTP connection warm. + */ + +import axios from "axios"; +import { + Keypair, + PublicKey, + SystemProgram, + TransactionInstruction, + TransactionMessage, + VersionedTransaction, + LAMPORTS_PER_SOL, +} from "@solana/web3.js"; +import { + ILandingProvider, + LandingResult, + SubmitOptions, + extractBlockhash, + pickRandom, +} from "../types"; + +// --------------------------------------------------------------------------- +// Config +// --------------------------------------------------------------------------- + +/** Vaults of the Apex tip program 9ig7pd4gqe2m16ACGPbPo4HfMGD3ba38poDhXEayx7EF. */ +const TIP_ACCOUNTS = [ + "APeX2oLtjYehgTMUCA971L8htM7tGNqsXHDz5NrivhhX", + "APeXAKT6spXSmU3uRv2MoEgQ7ckhAS4nexTgaxwLEfJ9", + "APeXB4mu1X7BSjwyPtiNUnKyhvc4wrq5SKEdmnPKWR95", + "APeXJTSGoxLWmwb9o1tiiEL5RXVUakazYgjLmZdDc2Ef", + "APeXUUaKFfPXjPxKHEdwCsJ4BfTuGg4qnVQyJE9K37PU", + "APeXVWXKDRAAujckMjmMsV61a4DQiXa98MPUAkL46sim", + "APeXW6PKFZRDz7WXBBybBMcoJaQo97UtLa5TAQnchNBY", + "APeXZuKaKuqouyfU8fFL1woeWvSEVFkY4EMrmkvbfhhD", + "APeXbYdbmrYWsastf6GurexGe3dwnuWKLD2mcsDoEuBU", + "APeXn29deoxpsZz6r7n63Ymmv2skBr3WhKYLB1mB2fR7", +] as const; + +const REGIONS = ["global", "fra", "ams", "dub", "lon", "nyc", "slc", "sgp", "tyo", "sqq"] as const; + +/** The standard tier's tip floor. A key's tier can set another; Apex rejects tips below it. */ +const DEFAULT_TIP_SOL = 0.001; + +function endpoint(): string { + if (process.env.APEX_URL) return process.env.APEX_URL; + const region = (process.env.APEX_REGION || "global").toLowerCase(); + if (!(REGIONS as readonly string[]).includes(region)) { + throw new Error(`Unknown APEX_REGION "${region}" (use one of: ${REGIONS.join(", ")})`); + } + return `http://${region}.apex.orbitflare.com`; +} + +// --------------------------------------------------------------------------- +// Provider +// --------------------------------------------------------------------------- + +function createProvider(): ILandingProvider { + return { + name: "apex", + + isEnabled(): boolean { + return !!process.env.APEX_API_KEY; + }, + + async ping(): Promise { + await axios.get(`${endpoint().replace(/\/+$/, "")}/ping`, { timeout: 5_000 }); + }, + + async submit( + ixs: TransactionInstruction[], + signer: Keypair, + blockhash: string | { blockhash: string; lastValidBlockHeight: number }, + opts: SubmitOptions, + ): Promise { + const provider = this.name; + try { + const key = process.env.APEX_API_KEY || ""; + if (!key) { + return { provider, accepted: false, error: "APEX_API_KEY not set" }; + } + + const tipSol = opts.tipSol && opts.tipSol > 0 ? opts.tipSol : DEFAULT_TIP_SOL; + + // Exactly one top-level transfer to an Apex tip account. The tip account is + // not in any lookup table, so it stays in the static keys as Apex requires. + const tipIx = SystemProgram.transfer({ + fromPubkey: signer.publicKey, + toPubkey: new PublicKey(pickRandom(TIP_ACCOUNTS)), + lamports: Math.round(tipSol * LAMPORTS_PER_SOL), + }); + + // Build V0 transaction — never mutate input ixs + const allIxs = [...ixs, tipIx]; + const bh = extractBlockhash(blockhash); + + const messageV0 = new TransactionMessage({ + payerKey: signer.publicKey, + recentBlockhash: bh, + instructions: allIxs, + }).compileToV0Message(opts.addressLookupTables); + + const tx = new VersionedTransaction(messageV0); + const signers: Keypair[] = [signer, ...(opts.extraSigners ?? [])]; + tx.sign(signers); + + const b64 = Buffer.from(tx.serialize()).toString("base64"); + const mevProtect = process.env.APEX_MEV_PROTECT === "true"; + + const t0 = Date.now(); + const response = await axios.post( + endpoint(), + { + jsonrpc: "2.0", + id: 1, + method: "sendTransaction", + // The third param is Apex's mevProtect flag. + params: [b64, { encoding: "base64" }, mevProtect], + }, + { timeout: 10_000, headers: { "x-api-key": key } }, + ); + const latencyMs = Date.now() - t0; + + const signature: string | undefined = response.data?.result; + if (signature) { + return { provider, accepted: true, signature, latencyMs }; + } + + const errMsg = + response.data?.error?.message || JSON.stringify(response.data?.error) || "Unknown apex error"; + return { provider, accepted: false, error: errMsg, latencyMs }; + } catch (err: any) { + return { + provider, + accepted: false, + error: err?.response?.data?.error?.message || err?.message || "apex request failed", + }; + } + }, + }; +} + +export { createProvider }; diff --git a/src/transactions/landing/tip-accounts.ts b/src/transactions/landing/tip-accounts.ts index 91d8eed9..78fa9491 100644 --- a/src/transactions/landing/tip-accounts.ts +++ b/src/transactions/landing/tip-accounts.ts @@ -124,6 +124,18 @@ export const TIP_ACCOUNTS: readonly TipAccount[] = [ { provider: "soyas", address: "soyascXFW5wEEYiwfEmHy2pNwomqzvggJosGVD6TJdY" }, { provider: "soyas", address: "soyasDBdKjADwPz3xk82U3TNPRDKEWJj7wWLajNHZ1L" }, { provider: "soyas", address: "soyasE2abjBAynmHbGWgEwk4ctBy7JMTUCNrMbjcnyH" }, + + // apex + { provider: "apex", address: "APeX2oLtjYehgTMUCA971L8htM7tGNqsXHDz5NrivhhX" }, + { provider: "apex", address: "APeXAKT6spXSmU3uRv2MoEgQ7ckhAS4nexTgaxwLEfJ9" }, + { provider: "apex", address: "APeXB4mu1X7BSjwyPtiNUnKyhvc4wrq5SKEdmnPKWR95" }, + { provider: "apex", address: "APeXJTSGoxLWmwb9o1tiiEL5RXVUakazYgjLmZdDc2Ef" }, + { provider: "apex", address: "APeXUUaKFfPXjPxKHEdwCsJ4BfTuGg4qnVQyJE9K37PU" }, + { provider: "apex", address: "APeXVWXKDRAAujckMjmMsV61a4DQiXa98MPUAkL46sim" }, + { provider: "apex", address: "APeXW6PKFZRDz7WXBBybBMcoJaQo97UtLa5TAQnchNBY" }, + { provider: "apex", address: "APeXZuKaKuqouyfU8fFL1woeWvSEVFkY4EMrmkvbfhhD" }, + { provider: "apex", address: "APeXbYdbmrYWsastf6GurexGe3dwnuWKLD2mcsDoEuBU" }, + { provider: "apex", address: "APeXn29deoxpsZz6r7n63Ymmv2skBr3WhKYLB1mB2fR7" }, ] as const; /** diff --git a/src/transactions/landing/types.ts b/src/transactions/landing/types.ts index 44faf44e..242ec821 100644 --- a/src/transactions/landing/types.ts +++ b/src/transactions/landing/types.ts @@ -2,8 +2,8 @@ * TX Landing Layer — Shared Types & Interfaces * * This module defines the provider interface and shared types used by - * all 12+ TX landing providers (0slot, nozomi, helius-sender, blockrazor, - * node1.me, bloXroute, astralane, stellium, flashblock, jito, nextblock, soyas). + * all 13 TX landing providers (0slot, nozomi, helius-sender, blockrazor, + * node1.me, bloXroute, astralane, stellium, flashblock, jito, nextblock, soyas, apex). * * Each provider implements ILandingProvider. The orchestrator calls them * using a uniform interface — no provider-specific logic leaks out. diff --git a/tests/apex-landing.test.ts b/tests/apex-landing.test.ts new file mode 100644 index 00000000..2d36c3d8 --- /dev/null +++ b/tests/apex-landing.test.ts @@ -0,0 +1,168 @@ +/** + * CI-safe tests for the OrbitFlare Apex landing provider — NO network, NO SOL. + * + * axios is mocked, so these check the transaction and request the provider builds. + */ + +import type axios from "axios"; +import { + Keypair, + PublicKey, + SystemProgram, + TransactionInstruction, + VersionedTransaction, +} from "@solana/web3.js"; + +import { getTipAccountsForProvider } from "../src/transactions/landing/tip-accounts"; + +// tests/setup.ts has already loaded the landing modules with the real axios, so load +// a fresh copy of the provider against a mocked one. +jest.mock("axios"); +let mockedAxios: jest.Mocked; +let createProvider: typeof import("../src/transactions/landing/providers/apex").createProvider; + +beforeAll(() => { + jest.isolateModules(() => { + mockedAxios = require("axios"); + ({ createProvider } = require("../src/transactions/landing/providers/apex")); + }); +}); + +const BLOCKHASH = "GHtXQBsoZHVnNFa9YevAzFr17DJjgHXk3ycTKD5xD3Zi"; +const MEMO_PROGRAM = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr"); +const ENV_KEYS = ["APEX_API_KEY", "APEX_REGION", "APEX_URL", "APEX_MEV_PROTECT"]; + +const signer = Keypair.generate(); +const memo = new TransactionInstruction({ + programId: MEMO_PROGRAM, + keys: [], + data: Buffer.from("apex test"), +}); +const opts = { dex: "raydium-amm-v4", operation: "buy" }; + +let savedEnv: Record; + +beforeEach(() => { + savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]])); + for (const k of ENV_KEYS) delete process.env[k]; + mockedAxios.post.mockReset(); + mockedAxios.get.mockReset(); +}); + +afterEach(() => { + for (const k of ENV_KEYS) { + if (savedEnv[k] === undefined) delete process.env[k]; + else process.env[k] = savedEnv[k]; + } +}); + +/** The transaction the provider posted, decoded. */ +function sentTx(): VersionedTransaction { + const body = mockedAxios.post.mock.calls[0][1] as any; + return VersionedTransaction.deserialize(Buffer.from(body.params[0], "base64")); +} + +/** Top-level SystemProgram transfers in the transaction, as [to, lamports]. */ +function transfers(tx: VersionedTransaction): [string, number][] { + const keys = tx.message.staticAccountKeys; + return tx.message.compiledInstructions + .filter((ix) => keys[ix.programIdIndex].equals(SystemProgram.programId)) + .map((ix) => [keys[ix.accountKeyIndexes[1]].toBase58(), Number(Buffer.from(ix.data).readBigUInt64LE(4))]); +} + +describe("Apex landing provider", () => { + test("is enabled only with APEX_API_KEY", () => { + expect(createProvider().isEnabled()).toBe(false); + process.env.APEX_API_KEY = "key"; + expect(createProvider().isEnabled()).toBe(true); + }); + + test("refuses to send without a key", async () => { + const r = await createProvider().submit([memo], signer, BLOCKHASH, opts); + expect(r).toMatchObject({ provider: "apex", accepted: false, error: "APEX_API_KEY not set" }); + expect(mockedAxios.post).not.toHaveBeenCalled(); + }); + + test("sends a signed transaction with exactly one Apex tip to the global endpoint", async () => { + process.env.APEX_API_KEY = "test-key"; + mockedAxios.post.mockResolvedValue({ data: { jsonrpc: "2.0", id: 1, result: "SIG" } }); + + const r = await createProvider().submit([memo], signer, BLOCKHASH, opts); + expect(r).toMatchObject({ provider: "apex", accepted: true, signature: "SIG" }); + + const [url, body, config] = mockedAxios.post.mock.calls[0] as any[]; + expect(url).toBe("http://global.apex.orbitflare.com"); + expect(config.headers).toEqual({ "x-api-key": "test-key" }); + expect(body.method).toBe("sendTransaction"); + expect(body.params[1]).toEqual({ encoding: "base64" }); + expect(body.params[2]).toBe(false); + + const tx = sentTx(); + expect(tx.message.recentBlockhash).toBe(BLOCKHASH); + expect(tx.message.staticAccountKeys[0].equals(signer.publicKey)).toBe(true); + const tips = transfers(tx); + expect(tips).toHaveLength(1); + expect(getTipAccountsForProvider("apex")).toContain(tips[0][0]); + expect(tips[0][0].startsWith("APeX")).toBe(true); + expect(tips[0][1]).toBe(1_000_000); + }); + + test("uses the caller's tip, region and MEV protection", async () => { + process.env.APEX_API_KEY = "k"; + process.env.APEX_REGION = "FRA"; + process.env.APEX_MEV_PROTECT = "true"; + mockedAxios.post.mockResolvedValue({ data: { result: "SIG" } }); + + await createProvider().submit([memo], signer, { blockhash: BLOCKHASH, lastValidBlockHeight: 1 }, { ...opts, tipSol: 0.0025 }); + + const [url, body] = mockedAxios.post.mock.calls[0] as any[]; + expect(url).toBe("http://fra.apex.orbitflare.com"); + expect(body.params[2]).toBe(true); + expect(transfers(sentTx())[0][1]).toBe(2_500_000); + }); + + test("APEX_URL overrides the region", async () => { + process.env.APEX_API_KEY = "k"; + process.env.APEX_REGION = "tyo"; + process.env.APEX_URL = "http://127.0.0.1:8080"; + mockedAxios.post.mockResolvedValue({ data: { result: "SIG" } }); + + await createProvider().submit([memo], signer, BLOCKHASH, opts); + expect(mockedAxios.post.mock.calls[0][0]).toBe("http://127.0.0.1:8080"); + }); + + test("leaves the tip floor to Apex, since a key's tier can set its own", async () => { + process.env.APEX_API_KEY = "k"; + mockedAxios.post.mockResolvedValue({ + data: { jsonrpc: "2.0", id: 1, error: { code: -32602, message: "tip 500000 is below your floor of 1000000 lamports" } }, + }); + const r = await createProvider().submit([memo], signer, BLOCKHASH, { ...opts, tipSol: 0.0005 }); + expect(transfers(sentTx())[0][1]).toBe(500_000); + expect(r).toMatchObject({ accepted: false, error: "tip 500000 is below your floor of 1000000 lamports" }); + }); + + test("an unknown region is an error, not a request", async () => { + process.env.APEX_API_KEY = "k"; + process.env.APEX_REGION = "mars"; + const r = await createProvider().submit([memo], signer, BLOCKHASH, opts); + expect(r.accepted).toBe(false); + expect(r.error).toContain('Unknown APEX_REGION "mars"'); + expect(mockedAxios.post).not.toHaveBeenCalled(); + }); + + test("surfaces Apex's JSON-RPC error", async () => { + process.env.APEX_API_KEY = "k"; + mockedAxios.post.mockResolvedValue({ + data: { jsonrpc: "2.0", id: 1, error: { code: -32001, message: "invalid API key" } }, + }); + const r = await createProvider().submit([memo], signer, BLOCKHASH, opts); + expect(r).toMatchObject({ accepted: false, error: "invalid API key" }); + }); + + test("ping hits /ping on the endpoint", async () => { + process.env.APEX_REGION = "ams"; + mockedAxios.get.mockResolvedValue({ data: "pong" }); + await createProvider().ping!(); + expect(mockedAxios.get.mock.calls[0][0]).toBe("http://ams.apex.orbitflare.com/ping"); + }); +});