User Info

Authenticated REST endpoints for account data.

Base URL: https://api.t.synchronicity.xyz/indexer

All endpoints on this page require both a valid _idx_session cookie (transport-level, required for every indexer request) and SIWE credentials (identity). Account IDs in responses will be returned as lowercase.

Authentication

Synchronicity uses SIWE (Sign-In With Ethereum) for authentication on both the REST API and WebSocket connections.

SIWE Message Format

Server configuration (testnet):


SIWE_DOMAIN=testnet.synchronicity.xyz
SIWE_URI=https://testnet.synchronicity.xyz/sign
SIWE_CHAIN_ID=1

The SIWE message must follow the EIP-4361 standard with these required field values:

Field	Value	Notes
`domain`	`testnet.synchronicity.xyz`	Case-insensitive
`uri`	`https://testnet.synchronicity.xyz/sign`	Must be HTTPS (HTTP allowed for localhost only)
`address`	Your account address	Must match the account you’re authenticating as
`chainId`	`1`	Must match exactly
`version`	`1`	Only version 1 is supported
`statement`	`Sign this message to access private data in Synchronicity.`	Must match exactly
`nonce`	Any string	Present in message but not validated server-side
`expirationTime`	ISO 8601 timestamp	Optional. If set, message is rejected after this time
`notBefore`	ISO 8601 timestamp	Optional. If set, message is rejected before this time

Example SIWE Message


testnet.synchronicity.xyz wants you to sign in with your Ethereum account:
0xAbC1230000000000000000000000000000000001

Sign this message to access private data in Synchronicity.

URI: https://testnet.synchronicity.xyz/sign
Version: 1
Chain ID: 1
Nonce: abc123
Issued At: 2025-06-01T00:00:00Z
Expiration Time: 2025-06-01T01:00:00Z

Signing

Sign the message using EIP-191 (personal_sign). The resulting signature is a hex string (e.g. 0x...).


// ethers.js v6
const message = buildSIWEMessage(/* fields */);
const signature = await signer.signMessage(message);


# web3.py
from eth_account.messages import encode_defunct
msg = encode_defunct(text=siwe_message)
signature = account.sign_message(msg).signature.hex()

REST API Credentials

Pass credentials via headers (preferred) or query parameters on every request:

Header	Query Parameter	Description
`X-Account-ID`	`account_id`	Account address
`X-SIWE-Message`	`siwe_message`	SIWE message string
`X-SIWE-Signature`	`siwe_signature`	Signature of the SIWE message

Headers take precedence if both are provided.


curl -H "X-Account-ID: 0xabc..." \
     -H "X-SIWE-Message: testnet.synchronicity.xyz wants you to sign in..." \
     -H "X-SIWE-Signature: 0x..." \
     https://api.t.synchronicity.xyz/indexer/api/account/0xabc...

Authentication Errors

All auth errors return 401 with a JSON body:


{ "error": "authentication expired" }

Error	Meaning
`Authentication required: account_id is missing`	Missing account ID
`Authentication required: SIWE message is missing`	Missing SIWE message
`Authentication required: SIWE signature is missing`	Missing signature
`Authentication required: account ID mismatch`	Message address doesn’t match provided account ID
`authentication expired`	`expirationTime` has passed
`authentication not yet valid`	Current time is before `notBefore`
`signature verification failed`	Invalid signature or address mismatch
`authentication domain mismatch`	Domain doesn’t match server config
`authentication URI mismatch`	URI doesn’t match server config
`authentication chain ID mismatch`	Chain ID doesn’t match server config
`authentication statement mismatch`	Statement doesn’t match expected value
`authentication version mismatch`	Version is not `"1"`
`invalid authentication URI format`	URI is not HTTPS (and not localhost)
`invalid authentication data`	Malformed message or missing fields

Account

`GET /api/account/:accountId`

Returns full account state: balances, active orders, positions, and recent history.

Path Parameters

Param	Type	Description
`accountId`	string	Account address

Query Parameters

Param	Type	Default	Description
`closed_orders_limit`	int	500	Max closed orders to return
`trades_limit`	int	500	Max trades to return
`liq_trades_limit`	int	500	Max liquidation trades to return
`funding_payments_limit`	int	500	Max funding payments to return
`twap_orders_limit`	int	500	Max TWAP orders to return

Limits are silently clamped to a maximum of 2000.

Response


{
  "accountId": "0xabc...",
  "data": {
    "balances": [Balance],
    "orderbooks": [ActiveOrderbook],
    "closed_orders": [Order],
    "trades": [Trade],
    "liquidation_trades": [LiquidationTrade],
    "funding_payments": [FundingPayment],
    "closed_twap_orders": [TWAPOrder]
  },
  "error": null
}

Balances

`GET /api/account/:accountId/balances`

Returns token balances for the account.

Path Parameters

Param	Type	Description
`accountId`	string	Account address

Response


{
  "accountId": "0xabc...",
  "balances": {
    "stoken_1qyqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq2z5dp7": {
      "token_id": "stoken_1qyqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq2z5dp7",
      "balance": "1000.00",
      "name": "USD Tether",
      "symbol": "USDT",
      "decimals": 6
    },
    "token_1nyl0e0yweragfsatygt24zmd8jrr2vqtvdfptzjhxkguz2xxx3vs0y07u7": {
      "token_id": "token_1nyl0e0yweragfsatygt24zmd8jrr2vqtvdfptzjhxkguz2xxx3vs0y07u7",
      "balance": "5.000000",
      "name": "SYNC",
      "symbol": "SYNC",
      "decimals": 6
    }
  },
  "error": null
}

Accounts will include a SYNC balance entry — this is the gas token used to pay transaction fees, and it is debited automatically every time the account pays gas. See Gas & Fees for details.

History

`GET /api/account/:accountId/account-history`

Returns only historical data (closed orders, trades, liquidations, funding, TWAP orders).

Path Parameters

Param	Type	Description
`accountId`	string	Account address

Query Parameters

Param	Type	Default	Description
`closed_orders_limit`	int	50	Max closed orders to return
`trades_limit`	int	50	Max trades to return
`liq_trades_limit`	int	50	Max liquidation trades to return
`funding_payments_limit`	int	50	Max funding payments to return
`twap_orders_limit`	int	50	Max TWAP orders to return

Limits are silently clamped to a maximum of 2000.

Response


{
  "accountId": "0xabc...",
  "data": {
    "closed_orders": [Order],
    "trades": [Trade],
    "liquidation_trades": [LiquidationTrade],
    "funding_payments": [FundingPayment],
    "closed_twap_orders": [TWAPOrder]
  },
  "error": null
}

Strategy Data

The authenticated user must own the strategy.

`GET /api/account/:accountId/strategies`

Returns trading strategies for the account.

Path Parameters

Param	Type	Description
`accountId`	string	Account address

Query Parameters

Param	Type	Default	Description
`status`	string	(all)	Filter by status: `"active"`, `"completed"`, `"cancelled"`
`limit`	int	25	Max strategies to return

limit is silently clamped to a maximum of 100.

Response


{
  "account_id": "0xabc...",
  "strategies": [Strategy],
  "error": null
}

`PATCH /api/strategies/:strategyId/metadata`

Update a strategy’s name and/or description. Both fields are optional.

Path Parameters

Param	Type	Description
`strategyId`	string	Strategy ID

Request Body


{
  "name": "My Strategy",
  "description": "Trend following on BTC"
}

Response


{
  "success": true,
  "error": null
}

`PATCH /api/strategies/:strategyId/coordinates`

Update node coordinates in a strategy graph.

Path Parameters

Param	Type	Description
`strategyId`	string	Strategy ID

Request Body


{
  "nodes": [
    {
      "node_id": "node_1",
      "coordinates": { "x": 100, "y": 200 }
    }
  ]
}

Response


{
  "success": true,
  "error": null
}

Data Types

All numeric values (prices, volumes, balances) are strings to preserve precision.
Timestamps on orders/trades are milliseconds (Unix epoch).
is_bid: true = buy, false = sell.
is_long: true = long, false = short.
account_id: lowercase string.
orderbook_id: uint64.
order_id: uint64.
trade_id: uint64.

Balance


{
  "token_id": "string",
  "balance": "string",
  "name": "string",
  "symbol": "string",
  "decimals": 0
}

ActiveOrderbook


{
  "orderbook_id": 1,
  "leverage": 10,
  "margin_type": "cross",
  "iso_orders_margin": "string | null",
  "iso_pos_margin_from_cross": "string | null",
  "position": "Position | null",
  "orders": [Order],
  "twap_orders": [TWAPOrder]
}

Position


{
  "cost": "string",
  "size": "string",
  "stop_losses": [{ "price": "string", "size": "string", "conditional_execution_id": "string", "price_type": "fixed | percentage", "percentage_bps": 20000 }],
  "take_profits": [{ "price": "string", "size": "string", "conditional_execution_id": "string", "price_type": "fixed | percentage", "percentage_bps": 20000 }]
}

Order


{
  "order_id": 1,
  "orderbook_id": 1,
  "price": "string",
  "is_bid": true,
  "order_type": "string",
  "size": "string",
  "size_filled": "string",
  "size_original": "string",
  "reduce_only": false,
  "parent_twap_id": "string | null",
  "sl_tp_side": "string | null",
  "client_order_id": "string | null",
  "stop_loss": { "price": "string | null", "size": "string", "price_type": "fixed | percentage", "percentage_bps": 20000 },
  "take_profit": { "price": "string | null", "size": "string", "price_type": "fixed | percentage", "percentage_bps": 20000 },
  "created_at": 1700000000
}

Trade


{
  "trade_id": 1,
  "order_id": 1,
  "orderbook_id": 1,
  "direction": "buy",
  "order_price": "string",
  "order_type": "string",
  "price": "string",
  "size": "string",
  "fee": "string",
  "closed_pnl": "string",
  "total_pnl": "string",
  "created_at": 1700000000
}

Trades are returned in descending trade_id order (most recent first).

LiquidationTrade


{
  "trade_id": 1,
  "is_adl": false,
  "orderbook_id": 1,
  "direction": "sell",
  "price": "string",
  "size": "string",
  "fee": "string",
  "closed_pnl": "string",
  "total_pnl": "string",
  "created_at": 1700000000
}

Liquidation trades are returned in descending trade_id order.

FundingPayment


{
  "orderbook_id": 1,
  "payment": "string",
  "size": "string",
  "is_long": true,
  "funding_rate": "string",
  "created_at": 1700000000
}

TWAPOrder


{
  "twap_id": "string",
  "orderbook_id": 1,
  "total_size": "string",
  "is_bid": true,
  "reduce_only": false,
  "frequency_ms": 60000,
  "slippage": 50,
  "start_time": 1700000000,
  "end_time": 1700003600,
  "total_executed_size": "string",
  "total_filled_size": "string",
  "remaining_size": "string",
  "elapsed_time": 1800,
  "status": "active",
  "cancellation_reason": "string | null",
  "created_at": 1700000000
}

Strategy


{
  "strategy_id": "string",
  "account_id": "string",
  "name": "string | null",
  "description": "string | null",
  "status": "active",
  "graph": {},
  "active_action_ids": ["string"],
  "failed_actions": { "action_id": "reason" },
  "positions": [
    {
      "orderbook_id": 1,
      "size": "string",
      "cost": "string",
      "upnl": "string"
    }
  ],
  "orders": [
    {
      "order_id": 1,
      "orderbook_id": 1,
      "price": "string",
      "size": "string",
      "is_bid": true
    }
  ],
  "total_upnl": "string",
  "created_at": 1700000000,
  "updated_at": 1700000000
}