TokenPlay CLOB Market Maker API

Market makers generate a new signature locally for each unique order payload. The private key stays in their bot or vault; TokenPlay only receives the resulting signature.

EVM orders are EIP-712 typed data signed against the ClobExchange contract for that chain.

import { Wallet } from "ethers";

const wallet = new Wallet(process.env.PRIVATE_KEY);
const chainId = 97;
const clobMarketId = 314n;
const clobExchange = process.env.CLOB_EXCHANGE;

const domain = {
  name: "tokenplay-clob-order-v1",
  version: "1",
  chainId,
  verifyingContract: clobExchange,
};

const types = {
  Order: [
    { name: "user", type: "address" },
    { name: "market", type: "uint256" },
    { name: "action", type: "uint8" },
    { name: "outcome", type: "uint8" },
    { name: "price", type: "uint256" },
    { name: "size", type: "uint256" },
    { name: "salt", type: "uint256" },
    { name: "expiry", type: "uint256" },
  ],
};

const message = {
  user: wallet.address,
  market: clobMarketId,
  action: 0,        // 0 = buy, 1 = sell
  outcome: 0,       // 0 = YES, 1 = NO
  price: 660n,      // 66.0c
  size: 18181818n,  // 18.181818 shares
  salt: BigInt(Date.now()) * 1000n,
  expiry: 0n,
};

const signature = await wallet.signTypedData(domain, types, message);

console.log(JSON.stringify({
  user: wallet.address,
  market: "evm:97:314",
  action: "buy",
  outcome: "YES",
  price: Number(message.price),
  size: message.size.toString(),
  type: "GTC",
  salt: Number(message.salt),
  expiry: Number(message.expiry),
  signature,
}, null, 2));

This must contain a fresh wallet signature for this exact payload. EVM orders are EIP-712 typed data signed against ClobExchange. The API does not take payment by itself; collateral must already be funded/deposited on-chain by the trading flow.

Click Send signed order

Cancel signature must be a wallet signature over: tokenplay-clob-cancel-v1|<user>|<orderId>.

This is an engine cancel, so there is no explorer transaction. Funds become idle/withdrawable in the CLOB exchange; use contract withdraw or npm run mm -- withdraw --amount <amount> to return them to the wallet.

Click Send cancel

// The message is signed exactly as for POST /orders — same domain, same struct.
// market inside the SIGNATURE is always the bare id; it is a uint256 on chain.
const signature = await wallet.signTypedData(
  { name: "tokenplay-clob-order-v1", version: "1", chainId: 97, verifyingContract: EXCHANGE },
  { Order: [
      { name: "user", type: "address" }, { name: "market", type: "uint256" },
      { name: "action", type: "uint8" }, { name: "outcome", type: "uint8" },
      { name: "price", type: "uint256" }, { name: "size", type: "uint256" },
      { name: "salt", type: "uint256" }, { name: "expiry", type: "uint256" } ] },
  { user: wallet.address, market: 314n, action: 0, outcome: 0,
    price: 700n, size: 10000000n, salt: 1725440000000n, expiry: 0n }
);

await fetch("https://app-staging.tokenplay.ai/clob-engine/market-order", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    chainId: 97,          // picks the EVM adapter — omit it and the request goes to Solana
    market: 314,          // the ON-CHAIN id, NOT the engine label "evm:97:314"
    user: wallet.address,
    action: "buy", outcome: "YES",
    price: 700,           // a LIMIT, not a target: quote first, then sign some slippage room
    size: "10000000",
    salt: 1725440000000, expiry: 0,
    signature,
  }),
});

Or, with the bundled client: npm run mm -- quote then npm run mm -- market-order --action buy --outcome YES --price 700 --size 10000000.

The mistake worth naming. Every other endpoint on the engine speaks the label evm:97:314, so a body built by copying a working POST /orders call carries it here too — and the EVM adapter reads it as a number, gets NaN, and answers 422 bad market id. There is no marketId field on this route; the field is market. Both spellings are accepted now, but the bare id is the one to write.

First, make sure the market exists on chain

On EVM, this is the public preparation call the UI shows as Preparing market.... Run it before the first deposit/order on a fresh market; otherwise deposit() can revert MarketMissing. On Solana, the same route is operator-only because it spends authority SOL to create accounts.

POST https://app-staging.tokenplay.ai/clob-engine/ensure-market
content-type: application/json

{"chainId": 97, "market": 314, "closeTime": 0}    ← EVM, no token

POST https://app-staging.tokenplay.ai/clob-engine/ensure-market
x-clob-resolve-token: <operator token>
content-type: application/json

{"marketId": 880101}                              ← Solana operator pre-provision

// 1. ask the bridge to assemble the Solana transaction
const res = await fetch("https://app-staging.tokenplay.ai/clob-engine/tx/deposit", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ marketId: 880101, user: wallet.publicKey.toBase58(), amount: "100000000" }),
}).then(r => r.json());
// { ok: true, transaction: "<base64>", blockhash, lastValidBlockHeight, createsTokenAccount }

// 2. sign it yourself — the only step that touches your key
const tx = Transaction.from(Buffer.from(res.transaction, "base64"));
tx.sign(wallet);

// 3. send it, here or straight to your own RPC
await fetch("https://app-staging.tokenplay.ai/clob-engine/tx/submit", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ signedTransaction: tx.serialize().toString("base64") }),
});
// { ok: true, signature: "…", confirmed: true }

The /tx/* routes are Solana-only. Do not add chainId to these calls; a body with chainId is routed to the EVM adapter, which does not serve /tx/*. /tx/submit waits for confirmation before it answers. Reading an account straight after a bare send is how a working instruction looks like it did nothing.

Claim is not withdraw

claim turns winning shares into free balance inside the exchange. withdraw is a second transaction that moves tokens to the wallet. Stopping after the first is the most common “where is my money”. remove-liquidity additionally needs the market resolved and the AMM pool to have claimed its own shares, or it reverts AmmNotSettled.

The same thing from a terminal

For trying it by hand before writing a client. EVM uses direct contract transactions through mm-client.mjs; Solana uses unsigned transaction builders or the local helper below.

# EVM, in prediction-backend
npm run mm -- ensure-market
npm run mm -- balance
npm run mm -- deposit --amount 25
npm run mm -- add-liquidity --amount 50
npm run mm -- claim-lp-fees
npm run mm -- remove-liquidity
npm run mm -- withdraw --amount <clobBalance>

# Solana, in tokenplay-clob-bridge
node scripts/solana-collateral.mjs balance 880101
node scripts/solana-collateral.mjs deposit 880101 100 --execute
node scripts/solana-collateral.mjs add-liquidity 880101 100 --execute
node scripts/solana-collateral.mjs claim 880101 --execute
node scripts/solana-collateral.mjs withdraw 880101 25 --execute

For EVM, claim is winnings only. LP exit is remove-liquidity, then withdraw. For Solana, solana-collateral.mjs is dry-run unless you pass --execute.

export ENGINE=https://app-staging.tokenplay.ai/clob/v1
export BRIDGE=https://app-staging.tokenplay.ai/clob-engine
export USER_PUB=<your base58 pubkey>
export M=880201                # the numeric market id

Amounts below are raw units: USDC has 6 decimals, so 50000000 is $50. Prices are ticks: 1000 = $1.00.

curl -s -X POST $BRIDGE/ensure-market   -H "x-clob-resolve-token: $TOKEN" -H 'content-type: application/json'   -d "{"marketId":$M}"
# {"ok":true,"market":880201}

curl -s "$BRIDGE/quote?market=$M"
# {"market":880201,"yes":500,"no":500}

curl -s $ENGINE/markets/$M
curl -s $ENGINE/markets/$M/book
curl -s $ENGINE/markets/$M/ticker

The first call is slow: it creates the accounts and funds the AMM. It is idempotent, so run it again freely.

You almost certainly do not need this step, or the token. x-clob-resolve-token is an operator secret — the same one that gates /propose and /resolve, which decide who gets paid — and it is not issued to integrators. A market published through the app is normally brought up on chain before you get to it; reading /quote for it will tell you. If a market really has no book, ask an operator to run this one call for it. Everything else below needs nothing but your own wallet.

# build — see what comes back before piping it anywhere
curl -s -X POST $BRIDGE/tx/deposit -H 'content-type: application/json'   -d "{"marketId":$M,"user":"$USER_PUB","amount":"50000000"}"
# {"ok":true,"transaction":"<base64>","blockhash":"…","createsTokenAccount":false}

# build → sign → submit, in one pipe
curl -s -X POST $BRIDGE/tx/deposit -H 'content-type: application/json'   -d "{"marketId":$M,"user":"$USER_PUB","amount":"50000000"}" | jq -r .transaction | node sign.mjs | curl -s -X POST $BRIDGE/tx/submit -H 'content-type: application/json' --data-binary @-
# {"ok":true,"signature":"…","confirmed":true}

sign.mjs is the whole of your side of this. It ships as scripts/sign.mjs in tokenplay-clob-bridge, and it is short enough to paste:

import { Transaction, Keypair } from "@solana/web3.js";
import bs58 from "bs58";

const wallet = Keypair.fromSecretKey(bs58.decode(process.env.USER_KEY));

let b64 = "";
process.stdin.setEncoding("utf8");
for await (const chunk of process.stdin) b64 += chunk;
b64 = b64.trim();

if (!b64 || b64 === "null") {
  // jq prints "null" when the build step returned an error instead.
  console.error("no transaction on stdin — run the /tx/... call alone and read its error");
  process.exit(1);
}

const tx = Transaction.from(Buffer.from(b64, "base64"));
tx.sign(wallet);
process.stdout.write(JSON.stringify({ signedTransaction: tx.serialize().toString("base64") }));

Run it as USER_KEY=<base58 secret key> node sign.mjs. This is a testing convenience: a real integration signs with the user's wallet — Phantom, a Ledger, a custodial signer — and the code is the same three lines, Transaction.from, sign, serialize. Nothing about the transaction is secret; only the signing is.

npm run mm:solana -- place --action buy --outcome YES --price 400 --size 5000000
# HTTP 201  {"accepted":true,"order":{"id":"o2","status":"open",…}}

curl -s $ENGINE/markets/$M/book
curl -s "$ENGINE/users/$USER_PUB/orders?market=$M"

export OID=$(curl -s $ENGINE/markets/$M/orders | jq -r '.orders[0].id')
curl -s $ENGINE/orders/$OID
# {"order":{"id":"o2","status":"open","remaining":"5000000"}}   ← no salt, no signature

npm run mm:solana -- cancel --id $OID
curl -s "$ENGINE/users/$USER_PUB/orders/closed?market=$M"

Swap place for message to print the signed string and the signature without sending anything — the fastest way to see why a signature is being rejected.

curl -s -X POST $ENGINE/orders -H 'content-type: application/json' -d "{
  "user":"$USER_PUB","market":"$M","action":"buy","outcome":"YES",
  "price":500,"size":"1000000","type":"GTC","salt":42,"expiry":0,
  "signature":"<any other valid base58 signature>"}"
# 422  {"accepted":false,"reason":"invalid signature"}

curl -s -X POST $BRIDGE/market-order -H 'content-type: application/json'   -d '{"market":880201,"user":"<pubkey>","action":"buy","outcome":"yes",
       "price":700,"size":5000000,"salt":123,"expiry":0,"signature":"<base58>"}'
# {"ok":true,"sig":"…","execPrice":500}

curl -s "$BRIDGE/quote?market=$M"
# {"yes":667,"no":333}    ← the AMM sold YES, so YES got dearer

Your signed price is a limit, not a request: 700 here means “fill me at 70¢ or better”, and it filled at 50¢. A 422 means the pool could not do it within your limit.

curl -s -X POST $BRIDGE/tx/add-liquidity -H 'content-type: application/json'   -d "{"marketId":$M,"user":"$USER_PUB","amount":"25000000"}" | jq -r .transaction | node sign.mjs | curl -s -X POST $BRIDGE/tx/submit -H 'content-type: application/json' --data-binary @-

curl -s -X POST $BRIDGE/resolve -H "x-clob-resolve-token: $TOKEN"   -H 'content-type: application/json' -d "{"marketId":$M,"outcome":"YES"}"
# {"ok":true,"txHash":"…","ammTx":"…"}      ← ammTx null means the pool held no shares

for k in claim claim-lp-fees remove-liquidity; do
  curl -s -X POST $BRIDGE/tx/$k -H 'content-type: application/json'     -d "{"marketId":$M,"user":"$USER_PUB"}"   | jq -r .transaction | node sign.mjs   | curl -s -X POST $BRIDGE/tx/submit -H 'content-type: application/json' --data-binary @-
done

# the balance after a claim is never a round number — read it, do not guess
curl -s -X POST $BRIDGE/tx/withdraw -H 'content-type: application/json'   -d "{"marketId":$M,"user":"$USER_PUB","amount":"76975000"}" | jq -r .transaction | node sign.mjs | curl -s -X POST $BRIDGE/tx/submit -H 'content-type: application/json' --data-binary @-

Leaving a placeholder in amount makes the build return an error, jq print null, and the signer choke on nothing. If a pipe dies oddly, run the /tx/ call alone and read its error.

Check the arithmetic, not just the status codes

Deposit $50, buy 5000000 at an exec price of 500, and the position should read $47.475: the trade cost $2.50 of notional and $0.025 of fee. After YES resolves, claim adds $5.00 — the shares are worth par — for $52.475. Removing $25 of liquidity returns $24.50, not $25: the pool sold shares for $2.50 that settled at $5.00, and your 25 of its 125 shares carry 20% of that $2.50 loss. A run where every call returns 200 and the totals do not close is a run that has quietly failed.

API Rate Limits

Defaults are intentionally generous and configurable per environment.