Understanding Liquidity

This guide explains how to fetch available markets, understand liquidity, and find or build order context hashes for trading.

Prerequisites

• Understand how BettorEdge Markets work (see What are BettorEdge Markets?)
• Have API access enabled and an API key (see Getting Started with API Access)

What is Liquidity?

Liquidity refers to existing orders in the market that you can trade against immediately:

• Someone has already placed an order at a specific price
• You can "take" their order by matching their price
• This results in an instant fill (trade execution)

No liquidity means:

• No one is currently offering that specific price
• You can place a new order and wait for someone to match you
• You become the liquidity provider

Fetching Available Markets

Use the /v1/markets/available endpoint to see currently available markets. This endpoint has two modes depending on whether you provide a league_id parameter.

Mode 1: Markets with Liquidity Only (No league_id)

When you don't provide a league_id, the endpoint returns only contests that have active liquidity (open orders):

cURL

curl -X GET https://proxy.bettoredge.com/markets/v1/markets/available \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://proxy.bettoredge.com/markets/v1/markets/available', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log('Markets with liquidity:', data.available_markets);

Python

response = requests.get(
    'https://proxy.bettoredge.com/markets/v1/markets/available',
    headers={
        'x-api-key': 'YOUR_API_KEY'
    }
)

data = response.json()
print('Markets with liquidity:', data['available_markets'])

Example: If there are two NBA games:

• Lakers vs Nuggets (has open orders) ✅ Returned
• Timberwolves vs Mavericks (no open orders) ❌ Not returned

Use this when: You want to find markets you can trade against immediately.

Mode 2: All Markets for a League (With league_ids)

When you provide league_ids, the endpoint returns all contests for the specified league(s), regardless of whether they have liquidity:

cURL

# Get all NBA markets (league_id = 2)
curl -X GET "https://proxy.bettoredge.com/markets/v1/markets/available?league_ids=2" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

// Get all NBA markets (league_id = 2)
const response = await fetch('https://proxy.bettoredge.com/markets/v1/markets/available?league_ids=2', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log('All NBA markets:', data.available_markets);

Python

# Get all NBA markets (league_id = 2)
response = requests.get(
    'https://proxy.bettoredge.com/markets/v1/markets/available',
    headers={
        'x-api-key': 'YOUR_API_KEY'
    },
    params={
        'league_ids': '2'
    }
)

data = response.json()
print('All NBA markets:', data['available_markets'])

Example: Using league_ids=2 (NBA) returns:

• Lakers vs Nuggets (has open orders) ✅ Returned
• Timberwolves vs Mavericks (no open orders) ✅ Returned

Use this when: You want to see all available contests for a league, even if there's no existing liquidity. You can place the first order on a new market.

Multiple Leagues: You can filter by multiple leagues using comma-separated values:

# Get markets for both NBA (2) and NFL (1)
curl -X GET "https://proxy.bettoredge.com/markets/v1/markets/available?league_ids=2,1" \
  -H "x-api-key: YOUR_API_KEY"

Getting League IDs

To get the correct league IDs, use the Get Leagues endpoint:

cURL

curl -X GET "https://proxy.bettoredge.com/events/v1/leagues/?status=active" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://proxy.bettoredge.com/events/v1/leagues/?status=active', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
// Extract league_id from the leagues you want
const nflLeague = data.leagues.find(l => l.league_name === 'NFL');
console.log('NFL league_id:', nflLeague.league_id); // "1"

Python

response = requests.get(
    'https://proxy.bettoredge.com/events/v1/leagues/',
    headers={
        'x-api-key': 'YOUR_API_KEY'
    },
    params={
        'status': 'active'
    }
)

data = response.json()
# Extract league_id from the leagues you want
nfl_league = next(l for l in data['leagues'] if l['league_name'] == 'NFL')
print('NFL league_id:', nfl_league['league_id'])  # "1"

Example Response:

{
  "message": "Success",
  "leagues": [
    {
      "league_id": "1",
      "league_name": "NFL",
      "sport": "football",
      "status": "active"
    },
    {
      "league_id": "2",
      "league_name": "NBA",
      "sport": "basketball",
      "status": "active"
    }
  ]
}

Then use the league_id in your available markets request:

# Get all NFL markets (league_id = 1)
curl -X GET "https://proxy.bettoredge.com/markets/v1/markets/available?league_ids=1" \
  -H "x-api-key: YOUR_API_KEY"

Understanding the Response

The response gives you all the components you need to build order context hashes:

{
  "message": "Success",
  "available_markets": [
    {
      "league_id": "2",
      "contests": [
        {
          "contest_type": "team",
          "contest_id": "lakers_nuggets_20240115",
          "contest_hash": "team:lakers_nuggets_20240115",
          "contest_title": "Lakers vs Nuggets",
          "markets": [
            {
              "market_id": 12345,
              "market_description": "Total Points Scored",
              "side_type": "athlete",
              "variable_required": true,
              "variable_options": [25.5, 28, 29, 31.5],
              "side_type_options": {
                "athletes": [
                  {
                    "athlete_id": "2954",
                    "first_name": "LeBron",
                    "last_name": "James",
                    "position": "F"
                  },
                  {
                    "athlete_id": "5821",
                    "first_name": "Anthony",
                    "last_name": "Davis",
                    "position": "F-C"
                  }
                ]
              },
              "sides": [
                {
                  "side": "over",
                  "side_type": "athlete",
                  "side_id": "2954",
                  "liquidities": [
                    {
                      "order_context_hash": "team:lakers_nuggets_20240115:12345:over:athlete:2954:26.5",
                      "variable": 26.5,
                      "price": 0.65,
                      "available": 100
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Breaking Down the Response

League Level

Field	Description
league_id	The sport/league numeric identifier (e.g., "1" for NFL, "2" for NBA)

Contest Level

Field	Description
contest_type	Type of event: "team", "tournament", or "match"
contest_id	Unique identifier for this specific game/event
contest_hash	First two components of order context hash
contest_title	Human-readable name (e.g., "Lakers vs Nuggets")

Market Level

Field	Description
market_id	Numeric ID for the market type (bigint)
market_description	Human-readable market name
side_type	What type of participant: "athlete", "team", or "side"
variable_required	Whether this market uses a line/variable
variable_options	Suggested lines (you can use any number)
side_type_options	Available athletes/teams if multiple_participants: true

Side Level

Field	Description
side	The prediction: "over", "under", "yes", "no", "home", "away"
side_type	Matches the market's side_type
side_id	The specific participant (athlete ID, team ID, or side)
liquidities	Array of existing orders you can trade against

Liquidity Object

Important: The liquidities array shows only the best available price for each market/side/variable combination.

Field	Description
order_context_hash	Complete hash you can use to place an order
variable	The line for this liquidity
price	Best available price (lowest price you can buy at)
available	Amount of liquidity available at this best price

Example:

LeBron over 26.5 points might have:
- $1,000 available at $0.60 ← Best price (shown in liquidities)
- $5,400 available at $0.65 ← Not shown (worse price)

The API only shows you the $0.60 price since that's the best deal for buyers. To see the full depth of the order book at all price levels, use the Order Book endpoint (coming soon).

Mapping Response to Hash Components

Let's see how each piece maps to the order context hash:

Hash Component	Where to Find It	Example Value
contest_type	contests[].contest_type	"team"
contest_id	contests[].contest_id	"lakers_nuggets_20240115"
market_id	markets[].market_id	12345
side	sides[].side	"over" or "under"
side_type	markets[].side_type	"athlete", "team", or "side"
side_id	side_type_options.athletes[].athlete_id	"2954"
variable	Your choice (check variable_options)	"31.5"

Two Ways to Get an Order Context Hash

Option A: Use Existing Liquidity

If there's already liquidity available (shown in the liquidities array), you can copy the order_context_hash directly:

// From the API response
const liquidity = market.sides[0].liquidities[0];
const orderContextHash = liquidity.order_context_hash;
// Result: "team:lakers_nuggets_20240115:12345:over:athlete:2954:26.5"

console.log(`Price: $${liquidity.price}`);
console.log(`Available: $${liquidity.available}`);

Benefits:

• Instant trade execution
• You know the exact price
• Someone is already offering this trade

Option B: Build Your Own Hash

To trade at a custom variable or for a different athlete, build the hash yourself:

// Get components from the API response
const contest = data.available_markets[0].contests[0];
const market = contest.markets[0];

// Step 1: Contest hash (first two components)
const contestType = contest.contest_type; // "team"
const contestId = contest.contest_id; // "lakers_nuggets_20240115"

// Step 2: Market ID
const marketId = market.market_id; // 12345

// Step 3: Your side (over or under)
const side = "over";

// Step 4: Choose athlete/team from side_type_options
// The market tells you the side_type (athlete, team, or side)
const sideType = market.side_type; // "athlete"

// If market.multiple_participants is true, the API response includes side_type_options
// with available athletes or teams to choose from
const athlete = market.side_type_options.athletes.find(a => a.first_name === "LeBron" && a.last_name === "James");
const sideId = athlete.athlete_id; // "2954"

// Step 5: Choose your variable/line
const variable = 31.5; // Can be any number, even if not in variable_options

// Build the order context hash
const orderContextHash = `${contestType}:${contestId}:${marketId}:${side}:${sideType}:${sideId}:${variable}`;
// Result: "team:lakers_nuggets_20240115:12345:over:athlete:2954:31.5"

Benefits:

• Trade at any line you want
• Create new markets
• Bet on any available participant

Examples of Different Hashes

Same market, different athletes:

LeBron James over 31.5 points:

team:lakers_nuggets_20240115:12345:over:athlete:2954:31.5

Anthony Davis under 28.5 points:

team:lakers_nuggets_20240115:12345:under:athlete:5821:28.5

Same athlete, different lines:

LeBron over 31.5 points:

team:lakers_nuggets_20240115:12345:over:athlete:2954:31.5

LeBron over 35 points:

team:lakers_nuggets_20240115:12345:over:athlete:2954:35.0

Understanding Variable Options

The variable_options array shows suggested lines where liquidity may exist:

"variable_options": [25.5, 28, 29, 31.5]

Important: You are NOT limited to these options!

• You can use any variable value
• Use 26.7, 30.0, 33.5, or any number you want
• Variable options are just suggestions based on market activity

Markets Without Variables

For markets where variable_required: false (like yes/no questions), use 0 as the variable:

team:lakers_nuggets_20240115:98765:yes:team:lakers_team_id:0

Reading Liquidity

Understanding Best Price

The liquidities array only shows the best available price for buyers:

What this means:

• You see the lowest price currently available
• This is the best deal you can get right now
• There may be more liquidity at higher prices (not shown)

Example scenario:

LeBron over 26.5 points order book:
┌─────────┬────────────┐
│ Price   │ Available  │
├─────────┼────────────┤
│ $0.60   │ $1,000     │ ← Best price (shown in API)
│ $0.62   │ $2,500     │ ← Not shown
│ $0.65   │ $5,400     │ ← Not shown
│ $0.68   │ $1,200     │ ← Not shown
└─────────┴────────────┘

The API response will only show:

{
  "order_context_hash": "team:lakers_nuggets_20240115:12345:over:athlete:2954:26.5",
  "variable": 26.5,
  "price": 0.60,
  "available": 1000
}

Why only show the best price?

• Simplifies the response
• Shows you the most important information (best deal)
• Reduces data transfer
• Most traders only care about the best price

To see full order depth: Use the Order Book endpoint (coming soon) to see all price levels and available liquidity at each level.

Understanding Price

Price represents the probability the market assigns to the outcome:

• $0.50 = 50% probability (coin flip)
• $0.65 = 65% probability (market thinks it's likely)
• $0.20 = 20% probability (market thinks it's unlikely)

Understanding Available Amount

The available field shows how much liquidity exists at the best price:

• 1000 = $1,000 worth of contracts available at this best price
• If you want more than $1,000, your order will partially fill at $0.60
• The rest of your order will either wait or fill at the next best price

Example: Large Order

// You want to buy $3,000 worth at $0.65 or better
// Best price: $0.60 with $1,000 available

// What happens:
// - $1,000 fills at $0.60 (best price)
// - Next $2,000 might fill at $0.62 (if available)
// - Or it waits as an open order at $0.65

Next Steps

Now that you understand how to find and build order context hashes:

• Place Your First Order - Learn how to execute a trade

---

Need help? Check out the Markets API Reference for detailed endpoint documentation.