Developers
HTTP API
The Socket API reads finalized chain state, quotes exactly, and prepares unsigned transactions. It holds no keys and submits nothing.
The API is what the app runs on. It reads pools, positions and hook state from finalized RPC, keeps an index of pools and swaps in PostgreSQL, and builds transactions for wallets to sign. It has no custody key and no route that sends a transaction.
On this site it is reachable at /api/socket, so GET /pools below is /api/socket/pools.
Conventions#
- JSON in and out. POST bodies must be
application/jsonand at most 64 KiB. - Token amounts, liquidity, square-root prices, nonces and slots are decimal strings. Ticks, fees in ppm and phases are numbers. Keys are base58.
- Errors are
{ "error": { "code": "…", "message": "…" } }with a 4xx status, or 503 when the RPC or database fails. - Every read says where it came from:
sourceisfinalized-rpc,finalized-postgresql-indexorfinalized-rpc-simulation.
Reads#
| Method | Route | Returns |
|---|---|---|
| GET | /health | { status: "ok" } while the process runs. |
| GET | /ready | { status, programId, finalizedSlot, indexedSlot } when the index is current; 503 when it is missing, stale or stopped. |
| GET | /config | The Socket program, the built-in hooks program, the genesis hash, the hook allowlist (configured hooks plus governance-listed ones), token labels, and the listing program, registry and governance program. |
| GET | /tokens | Mints in indexed pools with decimals and an optional label. |
| GET | /pools?limit=100&after=ADDRESS | Indexed pools, sorted by address, 1 to 500 per page. |
| GET | /pools/:address | The live pool, its mints and vault balances, and its resolved hook accounts. |
| GET | /pools/:address/hook | Built-in hook state, plus derived.dynamicFeePpm for a dynamic-fee pool at the server's current second. |
| GET | /pools/:address/activity?limit=50 | Recent swaps, newest first, 1 to 200, with hook compute per call. |
| GET | /pools/:address/twap?seconds=N | A TWAP read: { windowSeconds, startTimestamp, endTimestamp, meanTick }. |
| GET | /positions?owner=KEY | Every position of one owner, with current amounts, fees and whether it is in range. |
| GET | /transactions?limit=100&beforeSlot=N | Indexed program transactions and their logs. |
| GET | /listings | Every hook listing in the registry: hook, author, stake, proposed, listed or removed, and when. |
| GET | /governance?limit=50 | The realm, the governance, SOCKET's supply, the listing stake and its lock, the voting rules (votingSeconds, holdUpSeconds, yesThresholdPercent, yesThresholdWeight, proposeWeight) and recent proposals with their votes, deadlines and the listing each one changes. |
| GET | /governance/voters/:owner | One holder's deposit, wallet balance, open votes, and whether they can propose or withdraw. |
Quotes#
POST /quote/swap{ "pool": "<address>", "amount": "1000000000", "aToB": true, "exactIn": true }Returns the fee and where it came from (feeSource: "base" | "hook"), amountIn, amountOut, lpFee, amountRemaining (unspent input for a partial exact-in fill), ticksCrossed, maxSurcharge, the pool's price and liquidity before and after, the hook's kind and which swap phases it runs, and blocked when a filled range order would revert the swap.
POST /quote/liquidity{ "pool": "<address>", "lowerTick": -600, "upperTick": 600, "amountA": "1000000000" }Give exactly one of amountA or amountB. Returns the largest liquidity that amount buys in the range and both deposit amounts, rounded up. ONE_SIDED means that token isn't deposited in this range at the current price.
Quotes run the same math as the program against finalized state. They are estimates of what execution will do, not guarantees: send swaps with a slippage limit.
Prepare#
POST /prepare/:operation returns { transaction, blockhash, lastValidBlockHeight, requiredSigners }: a base64 unsigned legacy transaction with a compute-limit instruction first. Every request includes owner, the fee payer and signer, and may include computeUnits (10,000 to 1,400,000; default 1,000,000).
| Operation | Fields besides owner |
|---|---|
initialize | nonce, mintA, mintB, sqrtPrice, tickSpacing, baseFeePpm, maxFeePpm, maxDeltaBps, permissions, hookBudget, hookProgram, extras, optional hookInit (built-in hooks only). |
open-position | pool, nonce, lowerTick, upperTick. |
add-liquidity | pool, position, userA, userB, liquidity, maxA, maxB. Or open: true with nonce, lowerTick, upperTick to open and deposit in one transaction. |
remove-liquidity | pool, position, userA, userB, liquidity, minA, minB, optional collect: true. |
collect | pool, position, userA, userB. |
collect-hook-fees | pool, userA, userB, amountA, amountB. The owner must be the pool's creator. |
swap | pool, userA, userB, amount, limit, aToB, exactIn, threshold, maxTotalInput. |
cancel-order | pool. The owner must be the range order's owner. |
observe-twap | pool, secondsAgo. |
Listing and governance operations return { transactions: [...] } instead: the same unsigned transactions, in the order to send them. Most fit in one; a proposal or a withdrawal that releases many votes can take two.
| Operation | Fields besides owner |
|---|---|
listing-propose | hook, optional source (defaults to the owner's SOCKET account). Locks the listing stake. |
listing-withdraw | hook. The owner must be the author; the listing must be proposed or removed, and its lock passed. |
governance-deposit | amount, optional source. |
governance-withdraw | None. Releases finished votes, then returns the whole deposit. |
governance-propose | action (approve or remove), hook, optional burn for a removal, optional descriptionLink. Creates the proposal, adds its one transaction and opens the vote; the response includes proposal. |
governance-vote | proposal, approve. |
governance-finalize | proposal. Anyone, once the voting time has ended. |
governance-execute | proposal. Anyone, once the hold-up has passed. |
Liquidity, collection and swap operations accept createTokenAccounts: true: a missing associated token account of the owner is created in the same transaction. Any other missing account is an error.
Running your own#
The API is a Node service with a PostgreSQL index. It runs anywhere Node 22 does; set the RPC URL, the genesis hash, the program ID, the hook allowlist, the listing registry (SOCKET_LISTING_REGISTRY) and the database URL. Database migrations run when it starts. It is public by design: put rate limits and authentication at your ingress if you need them.