Report Trading Data

Report trading data for your engaged projects across different exchanges.

Overview

This endpoint allows you to submit market maker data for your engaged projects. The data includes liquidity metrics, order book depth, and trading volumes across different exchanges and trading pairs.

Endpoint: POST https://data.api.forgd.com/api/v1/report

Authentication: Required (API Key) (docs)

POST Request

Headers

Header	Type	Required	Description
Authorization	string	Yes	API key for authentication Check Authentication for more details
x-dry-run	boolean	No	Run validation without uploading data Check Dry Run Mode for more details

Request Body

Request Body Type

Request Body Type

type RequestBody = {
  data: {
    date: string // YYYY-MM-DD format
    exchangeId: string // CoinGecko exchange ID
    baseCoinId: string // CoinGecko project ID
    quoteCoinId?: string // CoinGecko quote coin ID
    quoteCoinSymbol?: string // Quote coin symbol (USD, EUR, etc.)
    bidDepth50?: number // Bid depth at 50 bps
    askDepth50?: number // Ask depth at 50 bps
    bidAskDepth50?: number // Total depth at 50 bps (deprecated: should be provided as bidDepth50 and askDepth50)
    bidDepth100?: number // Bid depth at 100 bps
    askDepth100?: number // Ask depth at 100 bps
    bidAskDepth100?: number // Total depth at 100 bps (deprecated: should be provided as bidDepth100 and askDepth100)
    bidDepth200?: number // Bid depth at 200 bps
    askDepth200?: number // Ask depth at 200 bps
    bidAskDepth200?: number // Total depth at 200 bps (deprecated: should be provided as bidDepth200 and askDepth200)
    bidAskSpread?: number // Bid-ask spread percentage value, ie. spread of 0.5% should be reported as 0.5 (not 0.005)
    orderFillVolumeMaker?: number // Maker order fill volume
    orderFillVolumeTaker?: number // Taker order fill volume
  }[]
}

Request Body Example JSON

{
  "data": [
    {
      "date": "2024-03-14",
      "exchangeId": "binance",
      "baseCoinId": "solana",
      "quoteCoinId": "tether",
      "bidDepth50": 809,
      "askDepth50": 971,
      "bidDepth100": 1380,
      "askDepth100": 1520,
      "bidDepth200": 2180,
      "askDepth200": 2320,
      "bidAskSpread": 0.1,
      "orderFillVolumeMaker": 8902,
      "orderFillVolumeTaker": 23479
    },
    {
      "date": "2024-03-14",
      "exchangeId": "binance",
      "baseCoinId": "solana",
      "quoteCoinSymbol": "EUR",
      "bidDepth50": 456,
      "askDepth50": 523,
      "bidDepth100": 789,
      "askDepth100": 856,
      "bidDepth200": 1245,
      "askDepth200": 1321,
      "bidAskSpread": 0.15,
      "orderFillVolumeMaker": 5432,
      "orderFillVolumeTaker": 15678
    }
  ]
}

Request Body Fields

Field	Type	Required	Description
date	string	required	Trading date in YYYY-MM-DD format
exchangeId	string	required	Exchange ID from list of available exchanges Available also on exchanges endpoint
baseCoinId	string	required	Base coin ID from projects endpoint
quoteCoinId	string	conditional	Quote coin id from list of available coins Required for trading pairs against crypto currencies where quoteCoinSymbol is not provided - when to use
quoteCoinSymbol	string	conditional	Quote coin symbol (USD, EUR, etc.) from list of available currencies Required for trading pairs against fiat currencies where quoteCoinId is not provided - when to use
bidDepth50	number	optional default: 0	Bid depth at 50 bps (in USD)
askDepth50	number	optional default: 0	Ask depth at 50 bps (in USD)
bidAskDepth50	number	optional default: 0	Total depth at 50 bps (in USD) Deprecated: should be provided as bidDepth50 and askDepth50
bidDepth100	number	optional default: 0	Bid depth at 100 bps (in USD)
askDepth100	number	optional default: 0	Ask depth at 100 bps (in USD)
bidAskDepth100	number	optional default: 0	Total depth at 100 bps (in USD) Deprecated: should be provided as bidDepth100 and askDepth100
bidDepth200	number	optional default: 0	Bid depth at 200 bps (in USD)
askDepth200	number	optional default: 0	Ask depth at 200 bps (in USD)
bidAskDepth200	number	optional default: 0	Total depth at 200 bps (in USD) Deprecated: should be provided as bidDepth200 and askDepth200
bidAskSpread	number	optional default: 100	Bid-ask spread percentage value ie. spread of 0.5% should be reported as 0.5 (not 0.005)
orderFillVolumeMaker	number	optional default: 0	Maker order fill volume (in USD)
orderFillVolumeTaker	number	optional default: 0	Taker order fill volume (in USD)

When to use quoteCoinId and quoteCoinSymbol

Use quoteCoinId for trading pairs against crypto currencies:

• SOL/USDT (use quoteCoinId: 'tether')
• SOL/USDC (use quoteCoinId: 'usd-coin')
• SOL/BTC (use quoteCoinId: 'bitcoin')

Use quoteCoinSymbol for trading pairs against fiat currencies:

• SOL/USD (use quoteCoinSymbol: 'USD')
• SOL/EUR (use quoteCoinSymbol: 'EUR')
• SOL/KRW (use quoteCoinSymbol: 'KRW')

When quoteCoinId is set, quoteCoinSymbol will be ignored.

At least one of quoteCoinId or quoteCoinSymbol is required.

Examples

curl

curl -X POST "https://data.api.forgd.com/api/v1/report" \
  -H "Authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "date": "2024-03-14",
        "exchangeId": "binance",
        "baseCoinId": "solana",
        "quoteCoinId": "tether",
        "bidDepth50": 809,
        "askDepth50": 971,
        "bidAskSpread": 0.1,
        "orderFillVolumeMaker": 8902,
        "orderFillVolumeTaker": 23479
      }
    ]
  }'

javascript

const response = await fetch('https://data.api.forgd.com/api/v1/report', {
  method: 'POST',
  headers: {
    Authorization: '<API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: [
      {
        date: '2024-03-14',
        exchangeId: 'binance',
        baseCoinId: 'solana',
        quoteCoinId: 'tether',
        bidDepth50: 809,
        askDepth50: 971,
        bidAskSpread: 0.1,
        orderFillVolumeMaker: 8902,
        orderFillVolumeTaker: 23479,
      },
    ],
  }),
})

const data = await response.json()

if (response.ok) {
  console.log('Report:', data)
} else {
  console.error('Error:', response.status, response.statusText, data)
}

python

import requests

data = {
    "data": [
        {
            "date": "2024-03-14",
            "exchangeId": "binance",
            "baseCoinId": "solana",
            "quoteCoinId": "tether",
            "bidDepth50": 809,
            "askDepth50": 971,
            "bidAskSpread": 0.1,
            "orderFillVolumeMaker": 8902,
            "orderFillVolumeTaker": 23479
        }
    ]
}

response = requests.post(
    'https://data.api.forgd.com/api/v1/report',
    headers={'Authorization': '<API_KEY>'},
    json=data
)

data = response.json()

if response.ok:
    print('Report:', data)
else:
    print('Error:', response.status_code, response.reason, data)

Success Response

HTTP 201 Created

Returns information about the uploaded data including counts of created and updated records.

Response Type

Response Type

type SuccessResponseType = {
  createdCount: number
  updatedCount: number
}

Response Example JSON

{
  "createdCount": 258,
  "updatedCount": 42
}

Error Responses

HTTP 400 Bad Request

There was an error in the request body. Please check the message field for more details, fix the errors and try again.

Response Type

type ErrorResponseType = {
  message: {
    path?: string
    message: string
  }[]
  error: string
  statusCode: number
}

Response Example JSON

{
  "message": [
    {
      "path": "data.0.askDepth50",
      "message": "Expected number, received null"
    },
    {
      "path": "data.5.bidDepth100",
      "message": "Expected number, received string"
    },
    {
      "path": "data.8.baseCoinId",
      "message": "Base coin with id 'foo' not matching any valid ticker id"
    }
  ],
  "error": "Bad Request",
  "statusCode": 400
}

HTTP 401 Unauthorized

The request could not be authenticated. Possible reasons:

• You have not attached an API Key to your request - see Authentication
• Your API key is invalid or has been removed - see Obtaining an API Key

Response Type

type ErrorResponseType = {
  message: string
  statusCode: number
}

Response Example JSON

{
  "message": "Unauthorized",
  "statusCode": 401
}

HTTP 5xx Internal Server Error

The request has failed due to an error on the server side. Most likely there is an internal issue with our server or network - please try again after couple of minutes.

We are getting notified about every 5XX response internally but if this is an recurring issue, please contact us at [email protected].

Dry Run Mode

You can test your data format without actually uploading by setting the x-dry-run header to true. This will validate your data and return the same response format without persisting the data.

javascript

const response = await fetch('https://data.api.forgd.com/api/v1/report', {
  method: 'POST',
  headers: {
    Authorization: '<API_KEY>',
    'Content-Type': 'application/json',
    'x-dry-run': 'true',
  },
  body: JSON.stringify({
    data: [...],
  }),
})

python

import requests

response = requests.post(
    'https://data.api.forgd.com/api/v1/report',
    headers={
        'Authorization': '<API_KEY>',
        'x-dry-run': 'true'
    },
    json={'data': [...]},
)

curl

curl -X POST "https://data.api.forgd.com/api/v1/report" \
  -H "Authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "x-dry-run: true" \
  -d '{"data": [...]}'

FAQ & Troubleshooting

Updating existing report data

To update the data, submit the report using this endpoint for the same date, exchangeId, baseCoinId and (quoteCoinId or quoteCoinSymbol). Response will contain the counts of created and updated records.

Deleting existing report data

Currently there is no way to delete the report data.

My bid-ask spread in the application is lower than the value I have reported

Common mistake is that the bid-ask spread is reported as a decimal value where 0.5% spread is reported as 0.0005 while it should be reported as 0.5. Please check the your integration and make sure you are reporting the value correctly.

To fix the issue, please submit your past reports again with the correct values and your data will be updated.