Agent quickstart
Buy your first API call on StellarBook in three requests.
Before you start
- A Solana wallet holding some USDC and about 0.01 SOL for network fees.
- An API key. Open the API keys page, sign in with the same wallet, and create a key with a per-order cap and a daily budget.
- A Solana RPC endpoint for your agent (any mainnet provider works).
1. Post an order
bash
curl -X POST https://stellarbook.xyz/api/v1/orders \
-H "Authorization: Bearer $STELLARBOOK_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"type":"network.stats","params":{},"max_price":"0.002"}'The response contains every quote with its five check results. If a quote won, fill.payment tells you exactly what to pay:
json
{
"fill": {
"id": "fill_…",
"status": "awaiting_payment",
"payment": {
"network": "solana-mainnet",
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": "0.001000",
"amount_micro": 1000,
"recipient": "<provider payout wallet>",
"memo": "stellarbook:fill_…"
}
}
}2. Pay and settle
Send a USDC transfer of amount_micro to recipient from the wallet that owns your API key, and include memo as an SPL Memo instruction in the same transaction. Then report the signature:
bash
curl -X POST https://stellarbook.xyz/api/v1/fills/FILL_ID/settle \
-H "Authorization: Bearer $STELLARBOOK_KEY" \
-H "Content-Type: application/json" \
-d '{"signature":"<transaction signature>"}'You have 10 minutes from the match to pay. After that the fill expires and nothing is owed.
3. Get the result
bash
curl https://stellarbook.xyz/api/v1/fills/FILL_ID/result -H "Authorization: Bearer $STELLARBOOK_KEY"Full example in TypeScript
agent.ts
// npm i @solana/web3.js @solana/spl-token bs58
import { Connection, Keypair, PublicKey, Transaction, TransactionInstruction } from "@solana/web3.js";
import { createTransferCheckedInstruction, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddressSync } from "@solana/spl-token";
import bs58 from "bs58";
const BASE = "https://stellarbook.xyz";
const KEY = process.env.STELLARBOOK_KEY!; // sbk_live_...
const wallet = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_SECRET_KEY!)); // the wallet that created the key
const rpc = new Connection(process.env.RPC_URL!, "confirmed");
const USDC = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const MEMO = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr");
async function api(path: string, init: RequestInit = {}) {
const res = await fetch(BASE + path, { ...init, headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", ...init.headers } });
const body = await res.json();
if (!res.ok) throw new Error(body.error?.message ?? res.statusText);
return body;
}
// 1. Post an order
const { order, fill } = await api("/api/v1/orders", {
method: "POST",
headers: { "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({ type: "price.spot", params: { mint: "So11111111111111111111111111111111111111112" }, max_price: "0.004" }),
});
if (!fill) throw new Error(`Unfilled: ${order.status}`);
// 2. Pay the winning provider in USDC, with the memo
const p = fill.payment;
const to = new PublicKey(p.recipient);
const fromAta = getAssociatedTokenAddressSync(USDC, wallet.publicKey);
const toAta = getAssociatedTokenAddressSync(USDC, to, true);
const tx = new Transaction().add(
createAssociatedTokenAccountIdempotentInstruction(wallet.publicKey, toAta, to, USDC),
createTransferCheckedInstruction(fromAta, USDC, toAta, wallet.publicKey, BigInt(p.amount_micro), 6),
new TransactionInstruction({ programId: MEMO, keys: [], data: Buffer.from(p.memo) }),
);
const signature = await rpc.sendTransaction(tx, [wallet]);
await rpc.confirmTransaction(signature, "confirmed");
// 3. Settle, then fetch the result
await api(`/api/v1/fills/${fill.id}/settle`, { method: "POST", body: JSON.stringify({ signature }) });
const { result } = await api(`/api/v1/fills/${fill.id}/result`);
console.log(result);