Docs
Sandlot speaks the Jupiter swap API (/swap/v1). Anything your agent already sends there works here. All amounts are raw token units, as strings, as on Jupiter.
Quickstart
- Open the dashboard, create a workspace and save its key.
- Add an agent, choose its starting SOL and USDC, and copy its key.
- Change your base address to
your Sandlot addressand send the agent key asx-api-key. - Skip signing when the response says it's paper.
const BASE = process.env.SWAP_BASE // this site's address
const headers = { "x-api-key": process.env.SANDLOT_KEY, "content-type": "application/json" }
const quote = await fetch(
`${BASE}/swap/v1/quote?inputMint=${inputMint}&outputMint=${outputMint}&amount=${amount}&slippageBps=50`,
{ headers },
).then((r) => r.json())
const order = await fetch(`${BASE}/swap/v1/swap`, {
method: "POST",
headers,
body: JSON.stringify({ quoteResponse: quote, userPublicKey: wallet }),
}).then((r) => r.json())
if (order.sandlot?.mode === "paper") {
record(order.sandlot) // no transaction to sign
} else {
await signAndSend(order.swapTransaction)
}
GET /swap/v1/quote
Passed through to the live route and returned unchanged. Accepted parameters: inputMint, outputMint, amount, slippageBps, swapMode, dexes, excludeDexes, restrictIntermediateTokens, onlyDirectRoutes, asLegacyTransaction, maxAccounts.
POST /swap/v1/swap
Send quoteResponse as you received it. userPublicKey is optional on paper and required on the real route. prioritizationFeeLamports sets the priority fee the fill pays; without it the default is 100,000 lamports.
On paper the response keeps Jupiter's top-level fields and adds a sandlot object:
| Field | Meaning |
|---|---|
swapTransaction | null on paper |
simulationError | null, or the reason a fill failed |
sandlot. | paper or live |
sandlot. | filled or failed (routed on the real route) |
sandlot. | slippage_exceeded or insufficient_funds |
sandlot. | Sandlot's order id. Not an on-chain signature. |
sandlot., outAmount | What actually moved in the book |
sandlot. | What your quote promised |
sandlot. | Slippage applied to this fill |
sandlot., rentLamports | What came off the SOL balance |
sandlot. | Slippage and fees together, in USD at live prices |
/swap/v1/swap-instructions isn't supported yet and returns 501.
Fill model
- Re-quote. The order is priced again against the live route. The amounts in your
quoteResponsedon't decide the fill, only its pair, size and limit do. - Slippage. 1 bp, plus half the route's price impact, plus a random 0 to 3 bps for latency. It's taken from the output on ExactIn and added to the input on ExactOut.
- Your limit. If the result breaches
otherAmountThresholdthe order fails withslippage_exceeded. The network fee is still charged, as it is on chain. - Settlement. 5,000 lamports base fee plus the priority fee come off SOL. The first time an agent holds a token, it also pays 2,039,280 lamports of account rent. A paper wallet that can't cover the order fails with
insufficient_fundsand pays nothing, because a real one would fail simulation before sending.
Route fees are already inside the live quote. Paper fills can't model what your own order would do to later prices, or fail for chain reasons such as congestion.
Day by day
Each UTC day gets a row on the agent's board: closing value, the day's profit and loss, fills, misses and costs. Paper agents are marked to live prices every 15 minutes, with or without orders. A token with no live price is left out of the value and flagged on that day's row.
Real route
From the agent's page, turn on the real route by typing its name and setting an order cap and a daily cap in USD. Nothing else about your agent changes: the same key and calls now return a real, unsigned transaction from Jupiter. Your agent signs and sends it. Sandlot never holds keys, and records routed orders without tracking whether they landed.
Orders over a cap return 422 and aren't routed. Quotes on the real route may carry a small referral fee, visible in platformFee. The dashboard shows when the real route is open.
Errors and limits
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | Malformed input; the message says which field |
| 401 | bad_key | Missing or wrong key |
| 403 | live_routing_closed | The real route isn't open |
| 422 | over_order_cap, over_day_cap, unpriced | Not routed |
| 429 | rate_limited | Limits per agent: 240 quotes and 120 orders a minute |
| 503 | quotes_unavailable | The live route can't be reached. Nothing was filled; retry. |