Documentation

Market Maker API

Programmatic access to all LP functions. Use the API to automate inventory management, configure spreads, monitor fills, and withdraw earnings without the web dashboard.

API key auth is coming soon. All endpoints are currently available via the web dashboard.

Last updated: 8 April 2026

Base URL

https://simplefx.io/api/v1/mm

Authentication

All requests must include your LP API key in the Authorization header. API keys are issued from the SimpleFX dashboard under Settings.

Request headerjson

Authorization: Bearer mm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed mm_live_ for production and mm_test_ for sandbox.

HTTP status	Meaning
401	Missing or invalid API key
403	Key is valid but does not have permission for this resource
429	Rate limit exceeded (60 req/min per key)

Account

Returns the authenticated LP account profile and status.

GET/api/v1/mm/account

Responsejson

{
  "id": "lp_01jqe...",
  "email": "mm@example.com",
  "walletAddress": "0x723A3D...155aBe",
  "isActive": true,
  "createdAt": "2026-01-15T10:00:00Z"
}

Balances

Returns current inventory balances for the LP wallet.

GET/api/v1/mm/balances

Responsejson

{
  "ntzs": "9452.000000000000000000",
  "usdc": "3.912500",
  "wallet": {
    "address": "0x723A3D...155aBe",
    "chain": "base"
  }
}

When the position is active, ntzs reflects the DB-tracked pool position. When inactive it reflects the raw on-chain wallet balance.

Rate & Quote

Returns the current oracle mid-market rate (TZS per USDC).

GET/api/v1/mm/rate

Responsejson

{
  "midRateTZS": 3750
}

Returns a quote for a specific swap amount with the LP spread applied.

GET/api/v1/mm/quote

Query parameters:

`fromToken`required	string	NTZS or USDC
`toToken`required	string	NTZS or USDC
`amount`required	number	Input amount (human-readable, not wei)
`slippageBps`	number	Slippage tolerance in bps. Default: 100

Example — GET /api/v1/mm/quote?fromToken=USDC&toToken=NTZS&amount=10json

{
  "fromToken": "USDC",
  "toToken": "NTZS",
  "amountIn": "10",
  "minAmountOut": "37312.5",
  "midRate": 3750,
  "spreadBps": 150,
  "protocolFeeBps": 10
}

Configure Spread

Updates the bid and ask spread for the LP position. Both values are in basis points. Min 10, max 500 per side.

PATCH/api/v1/mm/spread

`bidBps`required	integer	Bid spread in bps (nTZS → USDC direction). Min 10, max 500.
`askBps`required	integer	Ask spread in bps (USDC → nTZS direction). Min 10, max 500.

Request bodyjson

{
  "bidBps": 120,
  "askBps": 150
}

Responsejson

{
  "bidBps": 120,
  "askBps": 150,
  "updatedAt": "2026-04-08T09:30:00Z"
}

Activate / Deactivate

Activates or deactivates the LP position. Activating sweeps inventory from the LP wallet to the solver pool and makes the position available to the matching engine. Deactivating returns tokens to the LP wallet.

PATCH/api/v1/mm/activate

isActiverequired boolean true to activate, false to deactivate

Request bodyjson

{
  "isActive": true
}

Responsejson

{
  "isActive": true,
  "walletAddress": "0x723A3D...155aBe",
  "updatedAt": "2026-04-08T09:31:00Z"
}

Fill History

Returns the most recent 100 fills for the LP position, ordered newest first.

GET/api/v1/mm/fills

Responsejson

{
  "fills": [
    {
      "id": "fill_01jqe...",
      "fromToken": "USDC",
      "toToken": "NTZS",
      "amountIn": "10.000000",
      "amountOut": "37312.500000000000000000",
      "feesEarned": "37.312500000000000000",
      "txHash": "0xabc123...",
      "createdAt": "2026-04-08T09:28:00Z"
    }
  ]
}

Withdraw

Withdraws tokens from the LP wallet to an external address. The LP position must be deactivated before withdrawing the full balance.

POST/api/v1/mm/withdraw

`token`required	string	"ntzs" or "usdc"
`toAddress`required	string	Destination EVM address (0x...)
`amount`required	string	Human-readable amount e.g. "500.00"

Request bodyjson

{
  "token": "ntzs",
  "toAddress": "0xRecipient...",
  "amount": "500.00"
}

Responsejson

{
  "txHash": "0xdef456...",
  "status": "confirmed"
}

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	Insufficient permissions for this operation
NOT_FOUND	404	LP account or resource not found
INSUFFICIENT_BALANCE	400	Wallet balance too low for the requested operation
INSUFFICIENT_LIQUIDITY	400	Solver pool lacks enough output tokens
INVALID_AMOUNT	400	Amount is zero, negative, or non-numeric
INVALID_ADDRESS	400	Destination address failed checksum validation
SPREAD_OUT_OF_RANGE	400	Bid or ask bps outside the 10–500 range
POSITION_INACTIVE	400	Operation requires an active LP position
RATE_LIMIT	429	Exceeded 60 requests/minute for this API key
INTERNAL_ERROR	500	Unexpected server error — contact support

Integration Examples

Node.js / TypeScript

const BASE = 'https://simplefx.io/api/v1/mm'
const KEY = process.env.SIMPLEFX_API_KEY

async function getBalances() {
  const res = await fetch(`${BASE}/balances`, {
    headers: { Authorization: `Bearer ${KEY}` },
  })
  return res.json()
}

async function setSpread(bidBps: number, askBps: number) {
  const res = await fetch(`${BASE}/spread`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ bidBps, askBps }),
  })
  return res.json()
}

cURL

# Get current balances
curl https://simplefx.io/api/v1/mm/balances \
  -H "Authorization: Bearer mm_live_xxxx"

# Update spread
curl -X PATCH https://simplefx.io/api/v1/mm/spread \
  -H "Authorization: Bearer mm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"bidBps": 120, "askBps": 150}'