Skip to main content
POST
/
data
/
volumes
Get trade volumes
curl --request POST \
  --url https://clob.forka.st/data/volumes \
  --header 'Content-Type: application/json' \
  --data '
{
  "include_24h": true,
  "conditions": [
    {
      "condition_id": "0xf15d606b67011df3589a141a2deecc705ce8c4ce06754db4c4d7ef71f6232789",
      "token_ids": [
        "30630994248667897740988010928640156931882346081873066002335460180076741328029",
        "40291878431120995477788013247190715512811223344556677889900112233445566778899"
      ]
    },
    {
      "condition_id": "0x222606b67011df3589a141a2deecc705ce8c4ce06754db4c4d7ef71f6232789",
      "token_ids": [
        "55550994248667897740988010928640156931882346081873066002335460180076741328029"
      ]
    }
  ]
}
'
[
  {
    "condition_id": "0xf15d606b67011df3589a141a2deecc705ce8c4ce06754db4c4d7ef71f6232789",
    "status": 200,
    "volume": "98213.77",
    "volume_24h": "213.77"
  },
  {
    "condition_id": "0x222606b67011df3589a141a2deecc705ce8c4ce06754db4c4d7ef71f6232789",
    "status": 400,
    "error": "token_ids_must_have_two_entries"
  }
]
Aggregate matched volume for every condition and token pair supplied in the payload. The endpoint is optimized for dashboards: you can refresh up to 100 conditions per call, and the response always uses HTTP 207 Multi-Status so you can see the outcome of each condition independently.
No authentication headers are required. Only the JSON body described below is needed.

​
Request body

  • include_24h — optional boolean. Defaults to false; set to true to receive a volume_24h field per successful condition.
  • conditions — required array (1–100 entries). Each item must define a condition_id plus exactly two unique token_ids that belong to that condition. Duplicate tokens or empty strings trigger per-condition errors.
When a token ID is formatted correctly but does not exist on the book, the API still returns the condition with status: 200 and reports the volume as 0.0.

​
Response semantics

  • The HTTP response status is always 207 Multi-Status. Each element in the array contains condition_id, status, and either the aggregated volumes or an error string.
  • status: 200 entries include volume (total matched volume for the pair) and, when include_24h was true, volume_24h. Both values are returned as decimal strings.
  • status: 400 indicates a validation issue isolated to that condition (missing tokens, duplicate token IDs, blank strings, etc.).
  • status: 500 surfaces unexpected backend issues for that condition; retrying later is recommended.

​
Error reference

ErrorMeaning
conditions_array_must_contain_at_least_one_entryThe request body omitted conditions or sent an empty list.
maximum_of_100_conditions_allowedMore than 100 conditions were provided.
condition_id_cannot_be_emptycondition_id was blank.
token_ids_must_have_two_entriesA condition did not include exactly two token IDs.
token_id_cannot_be_emptyOne of the provided token IDs was blank.
token_ids_must_be_uniqueThe same token ID was repeated within a condition.
internal_errorUnexpected failure while fetching volume data.
Handle the array by checking each status. Successful entries may be mixed with error entries in the same response, so you can partially update your dashboards without rerunning the entire request.

Body

application/json

Payload for requesting aggregate trade volumes for specific condition IDs.

​
conditions
object[]
required

List of condition IDs to evaluate (max 100 entries). Each condition must supply exactly two token IDs.

Required array length: 1 - 100 elements
​
include_24h
boolean
default:false

Set to true to include volume_24h snapshots for each condition. Defaults to false when omitted.

Response

Multi-status response with per-condition volumes.

​
condition_id
string
required

Condition ID echoed from the request.

​
status
integer
required

HTTP-style status code for the individual condition (200, 400, or 500).

Example:

200

​
volume
string

Total matched volume for the token pair, encoded as a string. Present when status is 200.

Example:

"98213.77"

​
volume_24h
string

Matched volume over the trailing 24 hours, encoded as a string. Included only when include_24h was set to true and data is available.

Example:

"213.77"

​
error
string

Machine-readable error when status is 4xx/5xx.

Example:

"token_ids_must_have_two_entries"