Skip to content
Amoeba FarmAmoeba FarmAmoeba Farm Docs

SDK overview

ameba-sdk is Amoeba’s TypeScript and Rust SDK for capped futures. It wraps the futures API’s routes and its sponsored prepare, sign and submit flow, builds every futures instruction, decodes the market account, and lets you review a prepared transaction before you sign it.

What it contains

Section titled “What it contains”

The TypeScript package’s ameba-sdk/futures entry (also the root ameba-sdk entry) has:

Piece What it does
FuturesClient A typed client for the futures API’s routes: markets, book, depth, trades, candles, account, quote and quote-prepare, Earn (earn, earnAccount, earnActivity), and the sponsored prepare → sign → submit → wait flow, including the earnDeposit and earnWithdraw actions. send does all of it in one call.
FuturesMarket Builders for every futures instruction with exact account metas: deposit, withdraw, submit, close, cancel, quote, split, merge, redeem, transfer and the permissionless settlement steps.
FuturesEarnVault Builders for the Earn vault, one for the whole product: create, deposit, withdraw, and the operator’s fund and defund.
FuturesBook The market account decoder: header, traders, orders, maker ladders and steps, claims, the arc list the program verifies proposals against, and each trader’s lowest and highest value.
Review and signing preparedTransaction keeps a prepared message’s bytes exactly, signPrepared adds the owner’s signature, and reviewPrepared decodes every futures instruction (with its governance epoch) so you can check what you sign.
Proposals encodeProposal and decodeProposal, the program’s proposal codec.
Earn vault decodeVault, decodeVaultPosition and the vault and position addresses.
Math and names PDAs, sides, modes, exact payoff and unit math, and futures error names (0x46520000 + n).

It depends only on @solana/web3.js v1 and buffer, and runs in Node and browsers. Integers of 64 bits or more are bigint; builders reject out-of-range values instead of truncating them.

The Rust crate ameba_sdk re-exports Amoeba’s futures client crate as ameba_sdk::futures, which also has the exact package solver, Book::propose. See Rust and Petri.

Trading through the API

Section titled “Trading through the API”
import { FuturesClient, preparedTransaction, reviewPrepared, signPrepared } from "ameba-sdk/futures";


const api = new FuturesClient({ baseUrl: "https://api.amoeba.farm" });
const futuresProgram = (await api.config()).programs.futures;
const quote = await api.quote({ market: "RAMX", owner, side: "long", lo: 86, hi: 104, lots: 3 });


const prepared = await api.prepare(owner, "submit", {
  market: "RAMX", side: "long", lo: 86, hi: 104, lots: 3, limit: 180_000n,
});
console.log(reviewPrepared(preparedTransaction(prepared), futuresProgram)); // what you sign
const { signature } = await api.submit(prepared, signPrepared(prepared, keypair));
await api.wait(signature, { commitment: "confirmed" });

A non-2xx answer throws FuturesApiError with the status, the error name and the program logs.

Building transactions yourself

Section titled “Building transactions yourself”

FuturesBook.decode(accountData) reads a market account from chain, and FuturesMarket builds its instructions. Two things the SDK leaves to you:

  • The package. Submit and Quote carry a solved proposal. The TypeScript SDK does not solve packages: take the proposal from a transaction the API prepared, or compute it with the Rust client’s Book::propose.
  • The governance gate. Every futures instruction must be bound to the program’s governance gate before signing (GovernanceGateBinding.fromAccount(…).bind(ix)). Transactions the API prepares are bound already.

Send Submit with heapFrame() (256 KiB) and computeLimit() (1.4 million compute units).

What the SDK does not do

Section titled “What the SDK does not do”
  • It does not hold keys or sign for you without your keypair or wallet.
  • It does not decide whether an action is allowed. The program checks every amount and account when the transaction runs, against the book as it is then.
  • It does not compute fair prices. Prices come from the book.

Separate checks

Section titled “Separate checks”

Several independent things must line up before a transaction is safe to sign. Keep them apart in your code and your logs:

  1. Deployment identity. The chain’s genesis hash and the program addresses are the ones you trust. See Identity and compatibility.
  2. The transaction. It pays its fee from the sponsor, asks only for the signatures you expect, calls only the programs you expect, and does exactly what was asked. See Prepared transactions.
  3. Current state. The market is tradable and the book still allows the package. The program checks this when the transaction runs.
  4. Wallet approval. The owner signs exactly the bytes that were checked.

Next

Section titled “Next”