Markets

Overview

The Markets API provides endpoints for interacting with Ethos prediction markets. This includes searching markets, retrieving market details, viewing price and transaction history, checking holders, tracking activity, and accessing leaderboards.

Endpoints

Get Market Transaction History

GET /api/v1/markets/:profileId/tx/history

Description: Retrieves the transaction history for a specific market based on its associated profile ID.

Authentication Required: No

Parameters

Path Parameters

Name	Type	Required	Description
`profileId`	integer	Yes	Profile ID of the market to retrieve transaction history for.

Responses

Success Response

Code: 200 OK

Returns an array of transaction history objects, each containing the transaction hash, timestamp, type, and amount.
Returns a paginated list of transaction history objects for the specified market.

{
  "ok": true,
  "data": [
    {
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "timestamp": "2025-03-30T10:00:00.000Z",
      "type": "BUY",
      "amountWei": "1000000000000000000"
    },
    {
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "timestamp": "2025-03-29T14:30:00.000Z",
      "type": "SELL",
      "amountWei": "500000000000000000"
    },
    // ... more transaction history objects
  ]
  "data": {
    "values": [
      {
        "eventId": 851534,
        "marketId": 8,
        "actorAddress": "0x57E5D96c50ceE6bFa0Fc12dD7892Cf50B5892e91",
        "type": "SELL",
        "voteType": "trust",
        "votes": 17,
        "funds": "111418815322905231",
        "txHash": "0x1b833c4fa432df3b0bef27df41fcd993bc903f147b0ba9ebcf3c82ef0005353c",
        "timestamp": 1743213959
      },
      {
        "eventId": 844872,
        "marketId": 8,
        "actorAddress": "0x7B3D5e9Ab82D3390792793468854975004440Cf6",
        "type": "SELL",
        "voteType": "trust",
        "votes": 45,
        "funds": "296984191472517380",
        "txHash": "0xbd7d708ab9b979b0499ef148f5ad940643610982d01cd42530809b5e9223bbdd",
        "timestamp": 1743188997
      }
      // ... more transaction objects
    ],
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

Property	Type	Description
`ok`	boolean	Success status
`data`	array	Array of transaction history objects
`data[].txHash`	string	Transaction hash
`data[].timestamp`	string	Timestamp of the transaction (ISO 8601 format)
`data[].type`	string	Transaction type (BUY or SELL)
`data[].amountWei`	string	Transaction amount in wei
`data`	object	Paginated response object
`data.values`	array	Array of transaction history objects
`data.values[].eventId`	integer	Unique identifier for the event
`data.values[].marketId`	integer	Profile ID of the market
`data.values[].actorAddress`	string	Ethereum address of the actor performing the transaction
`data.values[].type`	string	Transaction type (BUY or SELL)
`data.values[].voteType`	string	Type of vote (trust or distrust)
`data.values[].votes`	integer	Number of votes involved in the transaction
`data.values[].funds`	string	Transaction amount in wei
`data.values[].txHash`	string	Transaction hash
`data.values[].timestamp`	integer	Timestamp of the transaction (Unix timestamp)
`data.total`	integer	Total number of transactions available
`data.limit`	integer	Maximum number of transactions returned in this response
`data.offset`	integer	Number of transactions skipped (for pagination)

Error Response

Code: 404 Not Found (Example: Market not found)

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Market not found"
  }
}

Example

Request

http GET https://api.ethos.network/api/v1/markets/1/tx/history

Notes

This endpoint is useful for fetching transaction history data for a specific market when its profile ID is known.
If the requested profileId does not correspond to an existing market, the request will fail with a 404 error.
The transaction history data is sorted by timestamp in descending order.
Pagination parameters (limit, offset) can be added as query parameters (e.g., ?limit=10&offset=20). The default limit is likely 50, offset 0.
A voteTypeFilter query parameter can be used to filter by ‘trust’ or ‘distrust’.

Get Market Holders

GET /api/v1/markets/:profileId/holders

Description: Retrieves the holders for a specific market based on its associated profile ID.

Authentication Required: No

Parameters

Path Parameters

Name	Type	Required	Description
`profileId`	integer	Yes	Profile ID of the market to retrieve holders for.

Responses

Success Response

Code: 200 OK

Returns an array of holder objects, each containing the Ethereum address and balance in wei.
Returns an object containing an array of holder objects, detailing their address, vote type, and total votes/shares.

{
  "ok": true,
  "data": [
    {
      "address": "0x9E2218375567BB466b81E38E1a8b599b6250408C",
      "balanceWei": "10000000000000000000"
    },
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "balanceWei": "5000000000000000000"
    },
    // ... more holder objects
  ]
  "data": {
    "all": [
      {
        "actorAddress": "0xa537a180163E08d7F4F4eE12878B14DA63726dF7",
        "isPositive": true,
        "total_amount": "213n",
        "marketId": 8,
        "voteType": "trust",
        "total": "213n"
      },
      {
        "actorAddress": "0x392dB93ac086264DD466cAB5a41E167529C0C73e",
        "isPositive": true,
        "total_amount": "189n",
        "marketId": 8,
        "voteType": "trust",
        "total": "189n"
      }
      // ... more holder objects
    ]
  }
}

Property	Type	Description
`ok`	boolean	Success status
`data`	array	Array of holder objects
`data[].address`	string	Ethereum address of the holder
`data[].balanceWei`	string	Balance of the holder in wei
`data`	object	Response data container
`data.all`	array	Array of holder objects
`data.all[].actorAddress`	string	Ethereum address of the holder
`data.all[].isPositive`	boolean	Whether the holder’s position is based on trust (true) or distrust (false) votes
`data.all[].total_amount`	string	Total amount of votes/shares held (BigInt string format)
`data.all[].marketId`	integer	Profile ID of the market
`data.all[].voteType`	string	Type of vote (trust or distrust)
`data.all[].total`	string	Total amount of votes/shares held (BigInt string format, possibly redundant)

Error Response

Code: 404 Not Found (Example: Market not found)

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Market not found"
  }
}

Example

Request

http GET https://api.ethos.network/api/v1/markets/1/holders

Notes

This endpoint is useful for fetching holder data for a specific market when its profile ID is known.
If the requested profileId does not correspond to an existing market, the request will fail with a 404 error.
The holder data is sorted by balance in descending order.
The holder data appears to be sorted by the total amount held, in descending order.
The total_amount and total fields use a string representation ending in ‘n’, indicating BigInt values.

Get Address Market Holdings

GET /api/v1/markets/holdings/:address

Description: Retrieves the market holdings for a specific Ethereum address.

Authentication Required: No

Parameters

Path Parameters

Name	Type	Required	Description
`address`	string	Yes	Ethereum address to retrieve market holdings for.

Responses

Success Response

Code: 200 OK

Returns an array of market holding objects, each containing the market profile ID, balance in wei, and market information.

{
  "ok": true,
  "data": [
    {
      "marketProfileId": 1,
      "balanceWei": "10000000000000000000",
      "market": {
        "marketProfileId": 1,
        "creatorAddress": "0x9E2218375567BB466b81E38E1a8b599b6250408C",
        "positivePrice": "13394648448485010",
        "negativePrice": "6605351551514990",
        "trustVotes": 1717,
        "distrustVotes": 16,
        "createdAt": "2024-09-14T00:00:00.000Z",
        "updatedAt": "2025-03-30T04:35:04.439Z",
        "basePrice": "10000000000000000",
        "creationCost": "100000000000000000",
        "liquidity": "1000",
        "configType": "NORMAL",
        "profile": {
          "primaryAddress": "0x9E2218375567BB466b81E38E1a8b599b6250408C",
          "avatarUrl": "https://pbs.twimg.com/profile_images/1797826077194096640/d_YEoB8n.jpg",
          "ethosScore": 1711,
          "name": "Ethos",
          "twitterUsername": "ethos_network"
        },
        "stats": {
          "marketCapWei": "7836838875288201409",
          "volumeTotalWei": "11279993864858341235",
          "volume24hWei": "10606200508522432",
          "priceChange24hPercent": 0
        }
      }
    },
    {
      "marketProfileId": 8,
      "balanceWei": "5000000000000000000",
      "market": {
        // ... market information for market profile ID 8
      }
    },
    // ... more market holding objects
  ]
}

Property	Type	Description
`ok`	boolean	Success status
`data`	array	Array of market holding objects
`data[].marketProfileId`	integer	Profile ID of the market
`data[].balanceWei`	string	Balance of the holder in wei
`data[].market`	object	Market information

Error Response

Code: 400 Bad Request (Example: Invalid address)

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "fields": [
      {
        "code": "invalid_address",
        "message": "Invalid Ethereum address",
        "path": ["address"]
      }
    ]
  }
}

Example

Request

http GET https://api.ethos.network/api/v1/markets/holdings/0x9E2218375567BB466b81E38E1a8b599b6250408C

Notes

This endpoint is useful for fetching market holding data for a specific Ethereum address.
If the requested address is not a valid Ethereum address, the request will fail with a 400 error.
The market holding data is sorted by balance in descending order.