# Activate subscription and retrieve API token
Source: https://txline-docs.txodds.com/api-reference/authentication/activate-subscription-and-retrieve-api-token
https://txline.txodds.com/docs/docs.yaml post /api/token/activate
Activate a user subscription and issue a long-lived API token.
Supports three modes based on the on-chain transaction:
1. Legacy subscriptions (pass empty leagues array).
2. Standard matrix subscriptions (pass empty leagues array).
3. Custom matrix subscriptions (pass requested league IDs up to the purchased limit).
The entire request intent must be cryptographically signed by the user's wallet.
# Start a new guest session
Source: https://txline-docs.txodds.com/api-reference/authentication/start-a-new-guest-session
https://txline.txodds.com/docs/docs.yaml post /auth/guest/start
Initiates a new, anonymous guest session and returns a JSON Web Token (JWT).
This token must be provided as a Bearer token in the Authorization header for subsequent calls,
such as the token activation endpoint. This JWT token expires after 30 days.
# Get a Merkle proof for a specific fixture update
Source: https://txline-docs.txodds.com/api-reference/fixtures/get-a-merkle-proof-for-a-specific-fixture-update
https://txline.txodds.com/docs/docs.yaml get /api/fixtures/validation
Each fixture returned or referenced in the TxODDS Oracle API is part of an hourly batch of fixture updates.
Blockchain holds the Merkle root (ultimate cryptographic containment proof) of each fixture belonging to that batch.
This endpoint returns the Merkle proof, i.e., the hashes along the branch of the Merkle tree for the batch up to but not inclusive of that Merkle root.
The user can then call on-chain validation directly to get a cryptographic validation that a given fixture update was published
by TxODDS as confirmed by the published Merkle root. This on-chain transaction requires the fixture record and the Merkle proof returned here.
# Get a Merkle proof for an entire hourly batch of fixtures
Source: https://txline-docs.txodds.com/api-reference/fixtures/get-a-merkle-proof-for-an-entire-hourly-batch-of-fixtures
https://txline.txodds.com/docs/docs.yaml get /api/fixtures/batch-validation
Fixture data is grouped into hourly batches. Each batch is represented by a Merkle Tree, and its root hash is published on-chain.
This Merkle root is contained within the batch's metadata.
This endpoint allows you to validate the integrity of the batch metadata itself. It returns the metadata for the specified hourly batch, along with a Merkle proof.
A user can take this proof and the metadata (which includes the final Merkle root) and use it to verify against a higher-level tree or commitment, thus cryptographically proving the integrity of the entire batch's claimed state.
# Get all fixture updates for a single fixture on a given day
Source: https://txline-docs.txodds.com/api-reference/fixtures/get-all-fixture-updates-for-a-single-fixture-on-a-given-day
https://txline.txodds.com/docs/docs.yaml get /api/fixtures/updates/{epochDay}/{hourOfDay}
# Get the latest snapshot of fixtures, optionally starting at or within 30 days after a given epoch day
Source: https://txline-docs.txodds.com/api-reference/fixtures/get-the-latest-snapshot-of-fixtures-optionally-starting-at-or-within-30-days-after-a-given-epoch-day
https://txline.txodds.com/docs/docs.yaml get /api/fixtures/snapshot
# Get a json array of all odd updates from a specific historical 5-minute interval
Source: https://txline-docs.txodds.com/api-reference/odds/get-a-json-array-of-all-odd-updates-from-a-specific-historical-5-minute-interval
https://txline.txodds.com/docs/docs.yaml get /api/odds/updates/{epochDay}/{hourOfDay}/{interval}
# Get a Merkle proof for a specific odds update
Source: https://txline-docs.txodds.com/api-reference/odds/get-a-merkle-proof-for-a-specific-odds-update
https://txline.txodds.com/docs/docs.yaml get /api/odds/validation
Each odds update is part of a batch whose state is committed to the blockchain via a Merkle root.
This endpoint returns the cryptographic proof for a single odds update, identified by its unique messageId.
The proof consists of the hashes along the branch of the Merkle tree, which can be used to reconstruct the root.
A user can then use this proof and the odds record in an on-chain transaction to cryptographically verify that the odds update was
published by the TxODDS Oracle as confirmed by the on-chain Merkle root.
# Get a real-time Server-Sent Events stream of odds updates
Source: https://txline-docs.txodds.com/api-reference/odds/get-a-real-time-server-sent-events-stream-of-odds-updates
https://txline.txodds.com/docs/docs.yaml get /api/odds/stream
A long-lived stream of odds updates.
The stream consists of two types of events:
1. **Data messages:** These have an `id` in the format `timestamp:index` and `data` containing a JSON object for a single Odds record.
2. **Heartbeats:** These have an `event` field set to `heartbeat` and may have data like `{"Ts": 12345}`.
# Get currently live odds updates for a single fixture
Source: https://txline-docs.txodds.com/api-reference/odds/get-currently-live-odds-updates-for-a-single-fixture
https://txline.txodds.com/docs/docs.yaml get /api/odds/updates/{fixtureId}
Return all available odds offers for a single fixture from the current, in-memory 5-minute cache.
# Get snapshots of the latest odds for a fixture
Source: https://txline-docs.txodds.com/api-reference/odds/get-snapshots-of-the-latest-odds-for-a-fixture
https://txline.txodds.com/docs/docs.yaml get /api/odds/snapshot/{fixtureId}
Return the latest odds for each unique market line for a given fixture. If the 'asOf' parameter is provided, the snapshots are taken at that point in time from historical data. Otherwise, it returns the current live snapshot if it exists within the current 5-minutes interval.
# Request a partially signed purchase quote given the wallet public key and required TxLINE amount in whole units
Source: https://txline-docs.txodds.com/api-reference/purchase/request-a-partially-signed-purchase-quote-given-the-wallet-public-key-and-required-txline-amount-in-whole-units
https://txline.txodds.com/docs/docs.yaml post /api/guest/purchase/quote
Authorize and generate a partially signed Solana transaction for purchasing TxLINE utility tokens.
**Pricing & Fees:**
- **Base Rate:** 1,000 TxLINE = 1 USDT
- **Premium/Markup:** Currently 0% (0 basis points)
**Prerequisites:**
- The `buyerPubkey` wallet must hold an active Associated Token Account (ATA) for USDT.
- The wallet must have a sufficient USDT balance to cover the total quoted cost.
The response includes a financial breakdown of the exact base cost and any applied premium fees. The returned transaction payload must be signed by the user's wallet before submission.
# Get a json array of all score updates from a specific historical 5-minute interval (no live data is returned)
Source: https://txline-docs.txodds.com/api-reference/scores/get-a-json-array-of-all-score-updates-from-a-specific-historical-5-minute-interval-no-live-data-is-returned
https://txline.txodds.com/docs/docs.yaml get /api/scores/updates/{epochDay}/{hourOfDay}/{interval}
# Get a Merkle multiproof for fixture statistics
Source: https://txline-docs.txodds.com/api-reference/scores/get-a-merkle-multiproof-for-fixture-statistics
https://txline.txodds.com/docs/docs.yaml get /api/scores/stat-validation-v3
This endpoint provides a deep cryptographic proof for statistics within a single scores update.
The TxODDS Oracle data is structured in a three-level Merkle hierarchy:
* A main batch contains summaries for multiple fixtures.
* Each fixture summary is the root of a sub-tree of all score update events for that fixture.
* Each score update event is the root of a sub-tree of all the individual statistics it contains.
This endpoint returns the full set of proofs needed to connect the stats all the way to the main batch root published on-chain.
### Request Format
The endpoint requires a comma-separated list of up to 5 keys in the `statKeys` parameter and returns a `ScoresStatValidationV3` payload supporting compressed multiproof validation.
### On-Chain Execution
With the returned data, the user can execute an on-chain transaction to validate that a supplied strategy holds against the extracted stats.
For example, validating that a team's score exceeded a threshold, or that the difference between two scores meets a specific binary condition.
# Get a Merkle proof for fixture statistics
Source: https://txline-docs.txodds.com/api-reference/scores/get-a-merkle-proof-for-fixture-statistics
https://txline.txodds.com/docs/docs.yaml get /api/scores/stat-validation
This endpoint provides a deep cryptographic proof for statistics within a single scores update.
The TxODDS Oracle data is structured in a three-level Merkle hierarchy:
1. A main batch contains summaries for multiple fixtures.
2. Each fixture summary is the root of a sub-tree of all score update events for that fixture.
3. Each score update event is the root of a sub-tree of all the individual statistics it contains.
This endpoint returns the full set of proofs needed to connect the stat(s) all the way to the main batch root published on-chain.
### Request Modes
The endpoint supports two mutually exclusive request formats:
* **Legacy Mode (`statKey`, `statKey2`)**: Returns a `ScoresStatValidation` payload containing proofs for one or two specific statistics.
* **V2 Mode (`statKeys`)**: Accepts a comma-separated list of keys and returns a `ScoresStatValidationV2` payload supporting dynamic N-dimensional proofs across any number of requested statistics.
### On-Chain Execution
With the returned data, the user can execute an on-chain transaction to validate that a supplied strategy holds against the extracted stats.
For example, validating that a team's score exceeded a threshold, or that the difference between two scores meets a specific binary condition.
# Get a real-time Server-Sent Events stream of scores updates
Source: https://txline-docs.txodds.com/api-reference/scores/get-a-real-time-server-sent-events-stream-of-scores-updates
https://txline.txodds.com/docs/docs.yaml get /api/scores/stream
A long-lived stream of scores updates.
The stream consists of two types of events:
1. **Data messages:** These have an `id` in the format `timestamp:index` and `data` containing a JSON object for a single Scores record.
2. **Heartbeats:** These have an `event` field set to `heartbeat` and may have data like `{"Ts": 12345}`.
# Get snapshots for each action in the latest score events for a fixture
Source: https://txline-docs.txodds.com/api-reference/scores/get-snapshots-for-each-action-in-the-latest-score-events-for-a-fixture
https://txline.txodds.com/docs/docs.yaml get /api/scores/snapshot/{fixtureId}
# Get the full sequence of score updates for a single fixture
Source: https://txline-docs.txodds.com/api-reference/scores/get-the-full-sequence-of-score-updates-for-a-single-fixture
https://txline.txodds.com/docs/docs.yaml get /api/scores/historical/{fixtureId}
Return a json array of all score updates for a single fixture provided its start time is between two weeks and six hours in the past from current time.
# Get the sequence of score updates for a single fixture within the current 5-min interval
Source: https://txline-docs.txodds.com/api-reference/scores/get-the-sequence-of-score-updates-for-a-single-fixture-within-the-current-5-min-interval
https://txline.txodds.com/docs/docs.yaml get /api/scores/updates/{fixtureId}
Return a json array of all score updates for a single fixture included within the current 5-minute interval with live data if it exists.
# Runnable Devnet Examples
Source: https://txline-docs.txodds.com/documentation/examples/devnet-examples
End-to-end devnet scripts for activation, streaming, and on-chain validation
The repository includes runnable devnet scripts under [`examples/devnet`](https://github.com/txodds/tx-on-chain/tree/main/examples/devnet). They exercise the current activation, streaming, fixture validation, and score validation flows against `https://txline-dev.txodds.com`.
The scripts use the devnet IDL and generated types in `examples/devnet/idl/txoracle.json` and `examples/devnet/types/txoracle.ts`. For mainnet integrations, use the root `idl/txoracle.json` and `types/txoracle.ts`, which include the latest mainnet program types.
## Requirements
* Node.js `20` or newer. The current lockfile resolves `eventsource@4.1.0`, which declares `node >=20.0.0`.
* A funded devnet wallet for `ANCHOR_WALLET`.
* `ANCHOR_PROVIDER_URL="https://api.devnet.solana.com"`.
* `TOKEN_MINT_ADDRESS=4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG`.
Install dependencies from the repository root:
```bash theme={null}
yarn install
```
Run a script with the devnet environment values:
```bash theme={null}
TOKEN_MINT_ADDRESS=4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG \
ANCHOR_PROVIDER_URL="https://api.devnet.solana.com" \
ANCHOR_WALLET="./_keys/testuser-wallet-1.json" \
yarn ts-node examples/devnet/scripts/subscription_free_tier.ts
```
## Script Index
| Script | What it demonstrates |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`subscription_free_tier.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_free_tier.ts) | Free-tier subscription activation, odds snapshot fetches, and odds SSE streams. |
| [`subscription_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores.ts) | Scores snapshots, recent score scanning, legacy `validateStat` with `statKey`, and scores SSE streams. |
| [`subscription_scores_1stat.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_1stat.ts) | Latest V2 score validation with one requested `statKeys` entry and `validateStatV2`. |
| [`subscription_scores_v2.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2.ts) | V2 validation with two stats, binary predicates, and geometric distance predicates. |
| [`subscription_scores_v2a.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2a.ts) | Rich multi-leg V2 validation with `statKeys=1,2,3001,3002` and two-, three-, and four-leg strategies. |
| [`subscription_scores_v3c.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v3c.ts) | V3 multiproof validation demonstrating both V2 and V3 validation approaches for comparison. |
| [`fixture_validation_view_only.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/fixture_validation_view_only.ts) | Fixture proof validation by simulation using the fixture validation endpoint and on-chain PDA. |
| [`historical_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/historical_scores.ts) | Fetching complete historical score updates for a specific fixture. |
The shared helpers are in `examples/devnet/common`:
| File | Purpose |
| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `config.ts` | Devnet API and guest JWT hosts. |
| `users.ts` | Wallet setup, free-tier subscription, activation signing, JWT renewal, API client setup, and transaction safety helpers. |
## Score Validation Paths
There are two score validation styles:
| API request | On-chain method | Use case |
| ---------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `/scores/stat-validation?fixtureId=...&seq=...&statKey=...` | `validateStat` | Single-stat or legacy two-stat examples using `statKey` and optional `statKey2`. |
| `/scores/stat-validation?fixtureId=...&seq=...&statKeys=1,2,...` | `validateStatV2` | Current multi-stat validation with indexed predicates and multi-leg strategies. |
For V2, the `statKeys` order is part of the proof contract. The response arrays `statsToProve` and `statProofs` are mapped by position, and strategy fields such as `index`, `indexA`, `indexB`, and `statIndex` refer to those same `0..N` positions.
```typescript theme={null}
const url = "/scores/stat-validation?fixtureId=18175981&seq=991&statKeys=1,2,3001,3002";
const val = (await users.apiClient.get(url)).data;
const payload = {
ts: new BN(val.summary.updateStats.minTimestamp),
fixtureSummary,
fixtureProof: mapProof(val.subTreeProof),
mainTreeProof: mapProof(val.mainTreeProof),
eventStatRoot: Array.from(val.eventStatRoot),
stats: val.statsToProve.map((statObj, index) => ({
stat: statObj,
statProof: mapProof(val.statProofs[index]),
})),
};
```
The fixed `fixtureId` and `seq` pairs in the example scripts are demo fixtures. In production, derive `fixtureId`, `seq`, phase, and status from an observed score record from snapshot, updates, historical data, or the scores stream.
## Final Outcome and Fixtures
On the current devnet and mainnet releases, final scores records use `action=game_finalised` with `statusId=100` and `period=100`. Use those records when validating or settling the final match outcome, regardless of whether the match ended after regulation time, extra time, penalties, or abandonment.
Fixture payloads include a backward-compatible `GameState` field. Current values are:
| GameState | Meaning |
| --------- | --------- |
| `1` | Scheduled |
| `6` | Cancelled |
Use `fixture_validation_view_only.ts` for the runnable fixture proof flow. The script demonstrates fetching fixture validation data, deriving the ten-day fixture roots PDA, and simulating `validateFixture`.
## Related Guides
* [Quickstart](/documentation/quickstart)
* [Streaming Data](/documentation/examples/streaming-data)
* [On-Chain Validation](/documentation/examples/onchain-validation)
* [Troubleshooting](/documentation/examples/troubleshooting)
# Fetching Snapshots
Source: https://txline-docs.txodds.com/documentation/examples/fetching-snapshots
Retrieve fixtures, odds, and scores data
**API Endpoints**: Use `https://txline.txodds.com/api/` for mainnet or `https://txline-dev.txodds.com/api/` for devnet
**Prerequisites**: Complete [Quickstart activation](/documentation/quickstart) first. The snippets assume `jwt` is the guest JWT from `/auth/guest/start` and `apiToken` is the value returned by `/api/token/activate`.
## Fetch Fixtures Snapshot
Get all fixtures for a specific competition or all competitions.
`Participant1IsHome` is the feed's home/away designation for mapping `Participant1` and `Participant2`; it is not a venue guarantee. For neutral competitions, `Participant1IsHome: true` means `Participant1` is listed as the home side for feed purposes, even if the match is not played in that team's country.
Fixture payloads include `GameState` in a backward-compatible format. Current values are `1` for scheduled fixtures and `6` for cancelled fixtures.
```typescript theme={null}
import axios from "axios";
const httpClient = axios.create({
timeout: 30000,
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${jwt}`,
"X-Api-Token": apiToken
},
baseURL: "https://txline.txodds.com",
});
// Get fixtures for specific competition
const fixturesResponse = await httpClient.get("/api/fixtures/snapshot", {
params: {
competitionId: 500005, // NCAA Division I FBS
},
});
const fixtures = fixturesResponse.data;
console.log(`Retrieved ${fixtures.length} fixtures`);
fixtures.slice(0, 3).forEach((fixture, index) => {
const homeTeam = fixture.Participant1IsHome
? fixture.Participant1
: fixture.Participant2;
const awayTeam = fixture.Participant1IsHome
? fixture.Participant2
: fixture.Participant1;
console.log(`${index + 1}. ${homeTeam} vs ${awayTeam}`);
console.log(` ID: ${fixture.FixtureId}, Start: ${new Date(fixture.StartTime).toISOString()}`);
console.log(` GameState: ${fixture.GameState ?? fixture.gameState}`);
});
// Get all fixtures
const allFixturesResponse = await httpClient.get("/api/fixtures/snapshot");
const allFixtures = allFixturesResponse.data;
console.log(`Retrieved ${allFixtures.length} total fixtures`);
```
## Fetch Odds Snapshot
Get odds data for a specific fixture or time period.
```typescript theme={null}
const fixtureId = 17271370;
// Get odds for specific fixture
const fixtureOddsResponse = await httpClient.get(
`/api/odds/snapshot/${fixtureId}`
);
const fixtureOdds = fixtureOddsResponse.data;
console.log(`Retrieved ${fixtureOdds.length} odds entries`);
// Get odds for time period
const epochDay = 20085;
const hourOfDay = 15;
const interval = 0;
const updatesResponse = await httpClient.get(
`/api/odds/updates/${epochDay}/${hourOfDay}/${interval}`
);
const updates = updatesResponse.data;
console.log(`Retrieved ${updates.length} odds updates`);
```
## Fetch Scores Snapshot
Get scores data for a specific fixture or time period.
```typescript theme={null}
const fixtureId = 17271370;
// Get scores snapshot for fixture
const snapshotScoresResponse = await httpClient.get(
`/api/scores/snapshot/${fixtureId}`
);
const snapshotScores = snapshotScoresResponse.data;
console.log(`Retrieved ${snapshotScores.length} snapshot scores entries`);
// Get live scores updates
const liveScoresResponse = await httpClient.get(
`/api/scores/updates/${fixtureId}`
);
const liveScores = liveScoresResponse.data;
console.log(`Retrieved ${liveScores.length} live scores updates`);
// Get scores for time period
const epochDay = 20085;
const hourOfDay = 15;
const interval = 0;
const historicalUpdatesResponse = await httpClient.get(
`/api/scores/updates/${epochDay}/${hourOfDay}/${interval}`
);
const historicalUpdates = historicalUpdatesResponse.data;
console.log(`Retrieved ${historicalUpdates.length} historical scores updates`);
```
# On-Chain Validation
Source: https://txline-docs.txodds.com/documentation/examples/onchain-validation
Validate scores data using cryptographic Merkle proofs
**Prerequisites**: Complete the [Quickstart](/documentation/quickstart) guide to set up authentication and subscriptions. The snippets assume `jwt` is the guest JWT from `/auth/guest/start` and `apiToken` is the value returned by `/api/token/activate`.
**API Endpoints**: Use `https://txline.txodds.com/api/` for mainnet or `https://txline-dev.txodds.com/api/` for devnet
**Program setup**: Use generated types that match your selected network, and use [Program Addresses](/documentation/programs/addresses), [Program Reference (Mainnet)](/documentation/programs/mainnet), or [Program Reference (Devnet)](/documentation/programs/devnet) for program IDs and PDA derivation.
## Overview
This guide demonstrates how to validate scores data against on-chain Merkle roots using cryptographic proofs. You'll learn how to fetch validation data and perform single-stat, two-stat, and V2 multi-stat validations.
The public `/api/scores/stat-validation` endpoint supports both validation shapes:
| Query shape | On-chain method | Notes |
| ----------------------------------------- | ---------------- | --------------------------------------------------------------- |
| `statKey=...` and optional `statKey2=...` | `validateStat` | Legacy single-stat and two-stat validation. |
| `statKeys=1,2,...` | `validateStatV2` | Current multi-stat validation with indexed strategy predicates. |
Use the same network for the API request, IDL/types, program ID, and on-chain root PDA.
The repository now includes runnable devnet examples for both paths in [`examples/devnet/scripts`](https://github.com/txodds/tx-on-chain/tree/main/examples/devnet/scripts). See [Runnable Devnet Examples](/documentation/examples/devnet-examples) for setup and script mapping.
## Validation Checklist
Before calling `validateStat`, confirm:
* The proof came from the same API host as your activated subscription.
* The program ID matches the network used for the proof.
* `daily_scores_roots` is derived from the same timestamp you pass into `validateStat`.
* The epoch day is encoded as u16 little-endian.
* Every proof hash is decoded to exactly 32 bytes.
* The fixture ID and sequence number refer to the score update you intend to validate.
* For V2, each strategy index refers to the same position in the requested `statKeys` array.
## Setup
```typescript theme={null}
import * as anchor from "@coral-xyz/anchor";
import { PublicKey, ComputeBudgetProgram } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
import axios from "axios";
const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);
const program = anchor.workspace.Txoracle as anchor.Program;
// Create HTTP client with authentication
const httpClient = axios.create({
timeout: 30000,
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${jwt}`,
"X-Api-Token": apiToken
},
baseURL: "https://txline.txodds.com",
});
// For devnet, use baseURL: "https://txline-dev.txodds.com".
function toBytes32(value: string | number[] | Uint8Array): number[] {
const bytes = Array.isArray(value)
? Uint8Array.from(value)
: value instanceof Uint8Array
? value
: value.startsWith("0x")
? Buffer.from(value.slice(2), "hex")
: Buffer.from(value, "base64");
if (bytes.length !== 32) {
throw new Error(`Expected 32 bytes, received ${bytes.length}`);
}
return Array.from(bytes);
}
function toProofNodes(nodes: Array<{ hash: string | number[] | Uint8Array; isRightSibling: boolean }>) {
return nodes.map((node) => ({
hash: toBytes32(node.hash),
isRightSibling: node.isRightSibling,
}));
}
```
## Fetching Scores Data
Retrieve a snapshot of scores for a specific fixture:
```typescript theme={null}
const fixtureId = 17952170;
const response = await httpClient.get(`/api/scores/snapshot/${fixtureId}?asOf=${Date.now()}`);
console.log(`Snapshot for fixture ${fixtureId}:`, response.data);
```
Search for recent score updates:
```typescript theme={null}
const now = new Date();
const targetTime = new Date(now.getTime() - (5 * 300000)); // 25 minutes ago
const epochDay = Math.floor(targetTime.getTime() / 86400000);
const hourOfDay = targetTime.getUTCHours();
const interval = Math.floor(targetTime.getUTCMinutes() / 5);
const updates = await httpClient.get(`/api/scores/updates/${epochDay}/${hourOfDay}/${interval}`);
console.log(`Updates found:`, updates.data);
```
## Choosing the Score Sequence
The `seq` parameter is not a placeholder. Use the sequence value from a real score record observed through one of the scores data endpoints:
* `/api/scores/snapshot/{fixtureId}`
* `/api/scores/updates/{epochDay}/{hourOfDay}/{interval}`
* `/api/scores/historical/{fixtureId}`
* `/api/scores/stream`
Do not call `/api/scores/stat-validation` with `seq=0`. Score sequences start at `1` for a fixture and increment as new score records are produced. Depending on your client and response mapper, the payload field may appear as `Seq` or `seq`; use that observed value when requesting the validation proof.
```typescript theme={null}
const scoreRecord = updates.data[0];
const seq = scoreRecord.Seq ?? scoreRecord.seq;
if (!Number.isInteger(seq) || seq < 1) {
throw new Error("Use a real score record sequence; seq=0 is not valid");
}
const validation = await httpClient.get("/api/scores/stat-validation", {
params: {
fixtureId: scoreRecord.FixtureId ?? scoreRecord.fixtureId,
seq,
statKey: 1002
}
});
```
## Phase and Status Semantics
Pick the score record whose game phase matches the condition you want to prove. For example, "final score of the first half" should use the record for the completed first-half phase or halftime/rest state, not an arbitrary in-running first-half update.
If you validate an in-running first-half record, the predicate means the condition was true at that observed moment. That is different from proving the final first-half result. Check the sport-specific phase tables, such as [Soccer Feed](/documentation/scores/soccer-feed), and use the score record's `statusId`, `StatusId`, `gameState`, or equivalent phase field when deciding whether a record is suitable for settlement.
For final match outcome settlement on the current devnet and mainnet releases, use a scores record with `action=game_finalised`. These finalisation records set `statusId` and `period` to `100`, so the same final-outcome validation path covers regulation-time wins, extra-time wins, penalty wins, and abandoned matches.
## Single-Stat Validation
Validate a single statistic against on-chain Merkle roots:
```typescript theme={null}
// Fetch validation data from API
const response = await httpClient.get("/api/scores/stat-validation", {
params: {
fixtureId: 17952170,
seq: 941,
statKey: 1002
}
});
const validation = response.data;
// Prepare fixture summary
const fixtureSummary = {
fixtureId: new BN(validation.summary.fixtureId),
updateStats: {
updateCount: validation.summary.updateStats.updateCount,
minTimestamp: new BN(validation.summary.updateStats.minTimestamp),
maxTimestamp: new BN(validation.summary.updateStats.maxTimestamp),
},
eventsSubTreeRoot: toBytes32(validation.summary.eventStatsSubTreeRoot),
};
// Prepare Merkle proofs
const fixtureProof = toProofNodes(validation.subTreeProof);
const mainTreeProof = toProofNodes(validation.mainTreeProof);
// Prepare stat to validate
const stat1 = {
statToProve: validation.statToProve,
eventStatRoot: toBytes32(validation.eventStatRoot),
statProof: toProofNodes(validation.statProof),
};
// Define validation predicate
const predicate = {
threshold: 0,
comparison: { greaterThan: {} },
};
// For a first sanity check, use exact equality if the response exposes
// validation.statToProve.value:
// const predicate = {
// threshold: validation.statToProve.value,
// comparison: { equalTo: {} },
// };
// Find the daily scores PDA
const targetTs = validation.summary.updateStats.minTimestamp;
const epochDay = Math.floor(targetTs / (24 * 60 * 60 * 1000));
const [dailyScoresPda] = PublicKey.findProgramAddressSync(
[
Buffer.from("daily_scores_roots"),
new BN(epochDay).toArrayLike(Buffer, "le", 2),
],
program.programId
);
// Execute validation using view (read-only simulation)
const computeBudgetIx = ComputeBudgetProgram.setComputeUnitLimit({
units: 1_400_000
});
try {
const isValid = await program.methods
.validateStat(
new BN(targetTs),
fixtureSummary,
fixtureProof,
mainTreeProof,
predicate,
stat1,
null, // No second stat
null // No operator
)
.accounts({
dailyScoresMerkleRoots: dailyScoresPda
})
.preInstructions([computeBudgetIx])
.view();
if (isValid) {
console.log("On-chain stat validation passed");
} else {
console.log("On-chain stat validation rejected the predicate");
}
} catch (err) {
console.error("Validation simulation failed:", err);
}
```
## Two-Stat Validation
Validate a comparison between two stats (e.g., score difference). This example builds on the single-stat validation above:
```typescript theme={null}
// Fetch validation data including a second stat
const response2 = await httpClient.get("/api/scores/stat-validation", {
params: {
fixtureId: 17952170,
seq: 941,
statKey: 1002,
statKey2: 1003
}
});
const validation2 = response2.data;
// Prepare second stat (stat1 is already defined above)
const stat2 = {
statToProve: validation2.statToProve2,
eventStatRoot: toBytes32(validation2.eventStatRoot),
statProof: toProofNodes(validation2.statProof2),
};
// Define operation and predicate
const op = { subtract: {} };
const predicate2 = {
threshold: 5,
comparison: { lessThan: {} },
};
// Execute two-stat validation (reuses variables from single-stat example)
const isValid2 = await program.methods
.validateStat(
new BN(targetTs),
fixtureSummary,
fixtureProof,
mainTreeProof,
predicate2,
stat1,
stat2,
op
)
.accounts({
dailyScoresMerkleRoots: dailyScoresPda,
})
.preInstructions([computeBudgetIx])
.view();
console.log("Two-stat validation result:", isValid2);
```
## V2 Multi-Stat Validation
Use `statKeys` when you need the current V2 payload and strategy model. The requested key order is important: the response arrays `statsToProve` and `statProofs` are mapped by position, and strategy fields such as `index`, `indexA`, `indexB`, and `statIndex` refer to those same `0..N` positions. Every stat in `payload.stats` must be covered exactly once by the strategy, or the program returns `IncompleteStatCoverage`.
```typescript theme={null}
const responseV2 = await httpClient.get("/api/scores/stat-validation", {
params: {
fixtureId: 18175981,
seq: 991,
statKeys: "1,2,3001",
},
});
const validationV2 = responseV2.data;
const targetTsV2 = validationV2.summary.updateStats.minTimestamp;
const epochDayV2 = Math.floor(targetTsV2 / (24 * 60 * 60 * 1000));
const [dailyScoresPdaV2] = PublicKey.findProgramAddressSync(
[
Buffer.from("daily_scores_roots"),
new BN(epochDayV2).toArrayLike(Buffer, "le", 2),
],
program.programId
);
const payload = {
ts: new BN(targetTsV2),
fixtureSummary: {
fixtureId: new BN(validationV2.summary.fixtureId),
updateStats: {
updateCount: validationV2.summary.updateStats.updateCount,
minTimestamp: new BN(validationV2.summary.updateStats.minTimestamp),
maxTimestamp: new BN(validationV2.summary.updateStats.maxTimestamp),
},
eventsSubTreeRoot: toBytes32(validationV2.summary.eventStatsSubTreeRoot),
},
fixtureProof: toProofNodes(validationV2.subTreeProof),
mainTreeProof: toProofNodes(validationV2.mainTreeProof),
eventStatRoot: toBytes32(validationV2.eventStatRoot),
stats: validationV2.statsToProve.map((stat: unknown, index: number) => ({
stat,
statProof: toProofNodes(validationV2.statProofs[index]),
})),
};
const strategy = {
geometricTargets: [],
distancePredicate: null,
discretePredicates: [
{
binary: {
indexA: 0, // statKeys[0] -> 1
indexB: 1, // statKeys[1] -> 2
op: { subtract: {} },
predicate: {
threshold: 0,
comparison: { equalTo: {} },
},
},
},
{
single: {
index: 2, // statKeys[2] -> 3001
predicate: {
threshold: 0,
comparison: { greaterThan: {} },
},
},
},
],
};
const isValidV2 = await program.methods
.validateStatV2(payload, strategy)
.accounts({
dailyScoresMerkleRoots: dailyScoresPdaV2,
})
.preInstructions([computeBudgetIx])
.view();
console.log("V2 validation result:", isValidV2);
```
For complete runnable versions, use:
| Script | V2 coverage |
| -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`subscription_scores_1stat.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_1stat.ts) | One requested stat with `validateStatV2`. |
| [`subscription_scores_v2.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2.ts) | Two-stat strategies and geometric validation. |
| [`subscription_scores_v2a.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2a.ts) | Multi-leg strategies using four requested stat keys. |
## Common Validation Errors
| Symptom | What to check |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `InvalidMainTreeProof` | Use the same `targetTs` for `validateStat` and `daily_scores_roots` PDA derivation. Confirm the proof hashes are exactly 32 bytes and not reversed. Confirm fixture ID and `seq` match the returned proof payload. |
| Account integrity passes but proof fails | The PDA is probably on the right network, but the timestamp, interval, or proof payload may not match the on-chain root. Recompute `epochDay = Math.floor(targetTs / 86400000)`. |
| Predicate returns false | First test with an exact predicate against the returned stat value, then replace it with your application predicate. |
| `IncompleteStatCoverage` | Ensure every entry in `payload.stats` is referenced exactly once by a discrete predicate or geometric target. Remove unused requested stats or add the missing strategy coverage. |
| V2 strategy validates the wrong stat | Confirm the requested `statKeys` order and the positional strategy indexes match. `index: 0` means the first requested key, not the smallest stat key. |
| `401` or `403` from the proof endpoint | Renew the guest JWT, keep the `X-Api-Token`, and confirm both credentials came from the same network host. |
See [Troubleshooting](/documentation/examples/troubleshooting) for the full activation, streaming, and validation checklist.
## Real-Time Scores Streaming
Subscribe to real-time scores updates:
```typescript theme={null}
const streamUrl = "https://txline.txodds.com/api/scores/stream";
const streamResponse = await fetch(streamUrl, {
headers: {
Authorization: `Bearer ${jwt}`,
"X-Api-Token": apiToken,
Accept: "text/event-stream",
"Cache-Control": "no-cache",
},
});
if (!streamResponse.ok) {
throw new Error(`Stream failed: ${streamResponse.status}`);
}
// Reuse the readSseMessages and parseSseData helpers from the Streaming Data guide.
for await (const message of readSseMessages(streamResponse)) {
console.log(message.event ?? "message", parseSseData(message.data));
}
```
## Validation Use Cases
On-chain validation enables trustless verification of:
* **Trading Settlement** - Prove score outcomes for bet settlement
* **Conditional Logic** - Execute smart contract logic based on verified game stats
* **Dispute Resolution** - Provide cryptographic proof of game data
* **Automated Markets** - Settle prediction markets with on-chain verification
* **Score Differentials** - Validate margins and score differences for complex betting scenarios
# Streaming Data
Source: https://txline-docs.txodds.com/documentation/examples/streaming-data
Real-time odds and scores updates via Server-Sent Events
**API Endpoints**: Use `https://txline.txodds.com/api/` for mainnet or `https://txline-dev.txodds.com/api/` for devnet
**Prerequisites**: Complete [Quickstart activation](/documentation/quickstart) first. The snippets assume `jwt` is the guest JWT from `/auth/guest/start` and `apiToken` is the value returned by `/api/token/activate`.
## Stream Expectations
An open SSE connection means your credentials and stream request are accepted. It does not guarantee that a covered fixture is producing data at that exact moment.
If the stream opens but you only see heartbeats or no data messages for a while:
* Check [Scores Schedule](/documentation/scores/schedule) for active or upcoming covered fixtures.
* Keep the stream open during a covered live fixture window.
* Use `/api/scores/historical/{fixtureId}` when you need replay data for a completed fixture within the historical availability window.
* Confirm you are using the correct network host for your subscription.
If a stream returns `401`, renew the guest JWT from the same host and reconnect with the same `X-Api-Token`. If it returns `403`, check that the API token belongs to the same network and subscription bundle.
## Runnable Devnet Streams
The repository includes runnable devnet stream scripts that handle activation, API token headers, JWT renewal, and SSE connections:
| Script | Stream coverage |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`subscription_free_tier.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_free_tier.ts) | Odds snapshots and odds SSE streams. |
| [`subscription_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores.ts) | Scores snapshots, score validation, and scores SSE streams. |
| [`subscription_scores_v2.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2.ts) | Scores stream handling alongside V2 score validation. |
| [`subscription_scores_v2a.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2a.ts) | Multi-leg V2 validation with multiple stat keys. |
| [`subscription_scores_v3c.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v3c.ts) | V3 multiproof validation comparing V2 and V3 approaches. |
| [`historical_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/historical_scores.ts) | Fetching historical score updates for completed fixtures. |
See [Runnable Devnet Examples](/documentation/examples/devnet-examples) for the required devnet environment variables and Node.js runtime notes.
## SSE Parsing Helper
```typescript theme={null}
type SseMessage = {
id?: string;
event?: string;
data: string;
retry?: number;
};
function parseSseBlock(block: string): SseMessage | null {
const message: SseMessage = { data: "" };
for (const rawLine of block.split(/\r?\n/)) {
if (!rawLine || rawLine.startsWith(":")) continue;
const separatorIndex = rawLine.indexOf(":");
const field = separatorIndex === -1 ? rawLine : rawLine.slice(0, separatorIndex);
const value =
separatorIndex === -1
? ""
: rawLine.slice(separatorIndex + 1).replace(/^ /, "");
if (field === "data") message.data += `${value}\n`;
if (field === "event") message.event = value;
if (field === "id") message.id = value;
if (field === "retry") message.retry = Number(value);
}
message.data = message.data.replace(/\n$/, "");
return message.data || message.event || message.id ? message : null;
}
async function* readSseMessages(response: Response): AsyncGenerator {
if (!response.body) throw new Error("Stream response has no body");
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
try {
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let separator = buffer.match(/\r?\n\r?\n/);
while (separator?.index !== undefined) {
const block = buffer.slice(0, separator.index);
buffer = buffer.slice(separator.index + separator[0].length);
const message = parseSseBlock(block);
if (message) yield message;
separator = buffer.match(/\r?\n\r?\n/);
}
}
buffer += decoder.decode();
const message = parseSseBlock(buffer);
if (message) yield message;
} finally {
reader.releaseLock();
}
}
function parseSseData(data: string) {
try {
return JSON.parse(data);
} catch {
return data;
}
}
```
## Stream Odds Updates
Connect to the odds stream for real-time updates.
```typescript theme={null}
const streamUrl = "https://txline.txodds.com/api/odds/stream";
const streamResponse = await fetch(streamUrl, {
headers: {
Authorization: `Bearer ${jwt}`,
"X-Api-Token": apiToken,
Accept: "text/event-stream",
"Cache-Control": "no-cache",
},
});
if (!streamResponse.ok) {
throw new Error(`Stream failed: ${streamResponse.status}`);
}
for await (const message of readSseMessages(streamResponse)) {
console.log(message.event ?? "message", parseSseData(message.data));
}
```
Use `https://txline-dev.txodds.com/api/odds/stream` for a devnet subscription.
## Stream Scores Updates
Connect to the scores stream for real-time updates.
```typescript theme={null}
const streamUrl = "https://txline.txodds.com/api/scores/stream";
const streamResponse = await fetch(streamUrl, {
headers: {
Authorization: `Bearer ${jwt}`,
"X-Api-Token": apiToken,
Accept: "text/event-stream",
"Cache-Control": "no-cache",
},
});
if (!streamResponse.ok) {
throw new Error(`Stream failed: ${streamResponse.status}`);
}
for await (const message of readSseMessages(streamResponse)) {
console.log(message.event ?? "message", parseSseData(message.data));
}
```
Use `https://txline-dev.txodds.com/api/scores/stream` for a devnet subscription.
Scores stream messages can be used as validation inputs. When a message contains a real sequence field, use its observed `Seq` or `seq` value with `/api/scores/stat-validation`; do not replace it with `0` or a synthetic sequence number.
## Historical Scores
Fetch the complete sequence of score updates for a fixture that started between two weeks and six hours ago.
```typescript theme={null}
import axios from "axios";
const httpClient = axios.create({
timeout: 30000,
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${jwt}`,
"X-Api-Token": apiToken
},
baseURL: "https://txline.txodds.com",
});
const fixtureId = 17952170;
const historicalScores = await httpClient.get(`/api/scores/historical/${fixtureId}`);
console.log(`Retrieved ${historicalScores.data.length} score updates for fixture ${fixtureId}`);
historicalScores.data.forEach((update, index) => {
console.log(`${index + 1}. Seq: ${update.seq}, TS: ${update.ts}, State: ${update.gameState}`);
});
```
Use the observed sequence from a historical record when requesting a validation proof for that record.
**Historical Availability**: This endpoint only returns data for fixtures with start times between two weeks and six hours in the past from the current time.
**Stream Compression**: To reduce bandwidth usage by up to 70-80%, add `"Accept-Encoding": "gzip"` to your headers. You'll need to decompress the response chunks using `gunzipSync()` from Node's `zlib` module before decoding.
## Troubleshooting
For activation, credential, and stream diagnostics, see [Troubleshooting](/documentation/examples/troubleshooting).
# Troubleshooting
Source: https://txline-docs.txodds.com/documentation/examples/troubleshooting
Diagnose common TxLINE onboarding, activation, streaming, and validation errors
## Before You Debug
Most integration issues come from one of four causes:
* Mixing devnet and mainnet values.
* Signing the wrong activation message.
* Using an expired or missing guest JWT.
* Deriving validation PDAs from a timestamp that does not match the proof payload.
Use one network consistently for every value:
| Network | Program ID | Guest JWT URL | Activation URL | API Base |
| ------- | ---------------------------------------------- | ------------------------------------------------ | -------------------------------------------------- | ------------------------------------ |
| Mainnet | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` | `https://txline.txodds.com/auth/guest/start` | `https://txline.txodds.com/api/token/activate` | `https://txline.txodds.com/api/` |
| Devnet | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` | `https://txline-dev.txodds.com/auth/guest/start` | `https://txline-dev.txodds.com/api/token/activate` | `https://txline-dev.txodds.com/api/` |
Never share your guest JWT, activated API token, wallet secret key, or unredacted request headers in public support channels.
## Activation Checklist
Before calling `/api/token/activate`, confirm:
* The on-chain `subscribe(serviceLevelId, durationWeeks)` transaction is confirmed.
* The `txSig` is from the same network as the activation endpoint.
* The guest JWT came from the same network host.
* The signing wallet is the same wallet that submitted the `subscribe` transaction.
* `walletSignature` is a base64-encoded detached signature.
* `leagues` is `[]` for the standard free tier bundle.
The activation message is:
```text theme={null}
${txSig}:${selectedLeagues.join(",")}:${jwt}
```
For `selectedLeagues = []`, sign:
```text theme={null}
${txSig}::${jwt}
```
## Runnable Example Checklist
When running the repository examples in `examples/devnet`, confirm:
* You are using Node.js `20` or newer. The current lockfile resolves `eventsource@4.1.0`, which requires `node >=20.0.0`.
* `ANCHOR_PROVIDER_URL` points to `https://api.devnet.solana.com`.
* `TOKEN_MINT_ADDRESS` is the devnet TxL mint `4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG`.
* The script imports the devnet IDL/types from `examples/devnet/idl` and `examples/devnet/types`.
* The wallet in `ANCHOR_WALLET` has enough devnet SOL for subscription transactions and account rent.
* Fixed `fixtureId` and `seq` pairs in example scripts are demo fixtures. For production, derive them from an observed score record.
* Final match outcome settlement should use scores records with `action=game_finalised`, `statusId=100`, and `period=100`.
* Fixture examples should expect the backward-compatible `GameState` field; current values are `1` for scheduled and `6` for cancelled.
## Common Errors
| Symptom | Likely cause | What to check |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Example script fails before connecting to TxLINE | Node runtime or environment variables do not match the current examples | Use Node.js `20+`, set `ANCHOR_PROVIDER_URL`, `ANCHOR_WALLET`, and `TOKEN_MINT_ADDRESS`, then run from the repository root |
| `504 Gateway Timeout` from `/api/token/activate` | Often a network mismatch, such as a devnet transaction sent to the mainnet activation host, or a backend timeout | Confirm `txSig`, guest JWT, program ID, and activation URL are all mainnet or all devnet |
| `403 signature verification failed` | Wrong signing preimage, wrong wallet, wrong signature encoding, or wrong JWT host | Sign the exact message string, use the subscribe wallet, send base64 detached signature, and use the matching network JWT |
| `401 Unauthorized` on data endpoints | Missing or expired guest JWT | Request a fresh guest JWT from the same host and retry with the same `X-Api-Token` |
| `403 Access denied` on data endpoints | Invalid API token, expired subscription, wrong network token, or insufficient subscription permissions | Confirm the `X-Api-Token` came from the same network and subscription bundle |
| `Invalid public key input` | Placeholder value was not replaced with a real Solana public key | Replace all placeholders with the program ID, TxL mint, and wallet public key for the selected network |
| SSE connection opens but no data messages arrive | The stream can be healthy even when no covered fixture is actively producing updates | Check the [Schedule](/documentation/scores/schedule), keep the stream open, or use historical endpoints for completed fixtures |
| `/api/scores/stat-validation` called with `seq=0` or a random `seq` | The sequence was treated as a placeholder instead of coming from a real score record | Get a score record from snapshot, updates, historical data, or the scores stream, then pass that record's observed `Seq` or `seq` value |
| `InvalidMainTreeProof` during validation | Timestamp, epoch day PDA, proof decoding, or fixture/update selection mismatch | Derive `daily_scores_roots` from the same timestamp passed to `validateStat`, decode hashes to exactly 32 bytes, and verify you are using the intended fixture and sequence |
| `validateStatV2` strategy checks the wrong value | `statKeys` order and positional strategy indexes were mixed up | Keep the requested `statKeys` order next to the strategy. `index`, `indexA`, `indexB`, and `statIndex` refer to `statsToProve[0..N]`, not to the numeric stat key itself |
| Final outcome settlement uses the wrong phase | The client selected an in-running or period-specific record instead of the match finalisation record | Use a scores record with `action=game_finalised`, `statusId=100`, and `period=100` |
## Auth Headers
Most data endpoints require both credentials:
| Header | Value |
| --------------- | ---------------------------------------------- |
| `Authorization` | `Bearer ` from `/auth/guest/start` |
| `X-Api-Token` | Activated API token from `/api/token/activate` |
If the guest JWT expires, request a new JWT from the same network host. You do not need to reactivate the API token unless the subscription or token itself is invalid.
## Stream Debugging
Server-Sent Events streams can send connection-level events, heartbeats, or no data for a period when there is no active covered fixture update.
When debugging streams:
* Use the matching host: `https://txline.txodds.com/api/...` for mainnet or `https://txline-dev.txodds.com/api/...` for devnet.
* Send both `Authorization` and `X-Api-Token`.
* Set `Accept: text/event-stream`.
* Treat an open connection with heartbeats as a live connection, not necessarily a data failure.
* Check [Scores Schedule](/documentation/scores/schedule) for active or upcoming covered fixtures.
* Use `/api/scores/historical/{fixtureId}` for a full replay when the fixture is already historical and within the supported historical window.
## Validation Debugging
For score validation, keep the API proof, PDA derivation, and on-chain call aligned:
```typescript theme={null}
const targetTs = validation.summary.updateStats.minTimestamp;
const epochDay = Math.floor(targetTs / (24 * 60 * 60 * 1000));
const [dailyScoresPda] = PublicKey.findProgramAddressSync(
[
Buffer.from("daily_scores_roots"),
new BN(epochDay).toArrayLike(Buffer, "le", 2),
],
program.programId
);
```
Pass the same `targetTs` into `validateStat`, and make sure every proof hash is decoded to exactly 32 bytes before passing it to Anchor.
Use a real score record sequence for `/api/scores/stat-validation`; `seq=0` is not valid. For settlement conditions tied to a period result, choose a record whose phase or status represents that completed period. An in-running record proves the condition at that moment, not the final result of the period.
For final match outcome settlement, use `action=game_finalised` records. Current devnet and mainnet releases set both `statusId` and `period` to `100` for those records.
For V2 validation, request multiple stats with `statKeys=1,2,...` and keep that order stable when building `statsToProve`, `statProofs`, and strategy predicates. See [Runnable Devnet Examples](/documentation/examples/devnet-examples) for complete `validateStatV2` scripts.
For a first sanity check, use an exact predicate against the returned stat value if your response shape includes `validation.statToProve.value`:
```typescript theme={null}
const predicate = {
threshold: validation.statToProve.value,
comparison: { equalTo: {} },
};
```
After this exact predicate succeeds, replace it with your application-specific predicate.
## Support Template
When opening a support ticket, include:
* Network: mainnet or devnet.
* Endpoint path and HTTP status.
* Program ID used.
* Service level ID and duration.
* Redacted transaction signature prefix/suffix.
* For activation: the selected leagues array and whether the signed message was `txSig::jwt`.
* For validation: fixture ID, sequence number, stat key, timestamp used, epoch day, and PDA.
* For V2 validation: the full `statKeys` list and the strategy indexes being checked.
* For final outcome validation: whether the selected score record had `action=game_finalised`, `statusId=100`, and `period=100`.
* For fixture validation: the fixture `GameState` value.
* Response body with secrets removed.
Do not include:
* Guest JWT.
* `X-Api-Token`.
* Wallet secret key.
* Full private request logs with authorization headers.
# FAQ
Source: https://txline-docs.txodds.com/documentation/faq
## General
**What is TxLINE?** TxLINE is a sports data API delivering fixtures, odds, scores, and settlement data, with every data point cryptographically verified on Solana, so your product never has to trust a middleman.
**Ready to build?** Go straight to our [Quickstart Guide](https://txline-docs.txodds.com/documentation/quickstart).
**Who is TxLINE designed for?** Developers, sportsbooks, betting exchanges, prediction markets, analytics platforms, and blockchain-based betting products.
**What makes TxLINE different from other sports data APIs?** Trustlessness. Traditional APIs require blind trust. TxLINE cryptographically anchors every score, odds figure, and fixture onto Solana via Merkle proofs. This lets you independently verify data timing and integrity permissionlessly, serving as the foundation for trustless smart-contract settlement.
**Where can I get help?** Documentation and an API reference are available at [txline-docs.txodds.com](http://txline-docs.txodds.com). Enterprise customers can access dedicated support with their Account Manager. Alternatively, email our helpdesk for further assistance at [hello@txodds.com](mailto:hello@txodds.com).
## Getting Started
**How quickly can I get started?** Most developers are up and running in minutes: create a Solana wallet, subscribe to a tier (the free tier requires no payment), activate an API token, and make your first request.
**What do I need before I start?** A Solana wallet is required to activate any subscription, including the free tier. For paid tiers, you'll also need USDT on the Solana network to purchase TxL tokens.
**Do I need a crypto wallet or cryptocurrency to use TxLINE?**
Crypto Wallet: Yes. A Solana wallet is strictly required for all tiers—including the free tier—because data entitlements and subscription states are recorded completely on-chain. Cryptocurrency: Not for the free tier. Paid subscriptions require TxL tokens, purchased using USDT on Solana (1 USD = 1,000 TxL). KYC verification may apply depending on compliance requirements.
**How do I purchase TxL tokens?** Fund your Solana wallet with USDT, request a purchase quote from the TxLINE backend, then verify, sign broadcast the transaction to Solana.
**Is KYC required?** KYC verification may be required for TxL token purchases depending on compliance requirements.
## Free Tier & World Cup
**Is there a free trial, and what does it include?** Yes. World Cup and International Friendlies data is free with no payment or credit card required. There are two free service tiers: 60-second delayed and real-time. You can find further information on subscription tiers here [https://txline-docs.txodds.com/documentation/subscription-tiers](https://txline-docs.txodds.com/documentation/subscription-tiers).
**What does the World Cup feed include?** The World Cup feed includes:
* Live scores and score updates
* Match events: goals, cards, substitutions, and more
* Match status and period changes
* Fixtures and scheduling data
* Odds data (via the StablePrice feed)
* Historical match data for replay and analysis
**Are there any other live event types planned for the World Cup feed?** The full list of supported event types is in the documentation at [txline-docs.txodds.com](http://txline-docs.txodds.com) or contact [hello@txodds.com](mailto:hello@txodds.com) for more information.
**Can I use the free tier for commercial projects?** Yes, including commercial projects. For production use cases we recommend upgrading for the best user experience with live in-play data and real-time access.
**Is there a rate limit on the free tier?** No rate limits. Free data applies to both 60-second delay and real-time tiers.
**Do I need to renew my free subscription?** Subscriptions run in 4-week increments. When access expires, simply re-subscribe. Free tier renewals are always no cost.
## Data & Sports Coverage
**What sports and competitions are available?** Football (Soccer) is currently supported, including the FIFA World Cup and International Friendlies on the free tier, plus over 1,000 leagues via paid plans. We also feature premium, in-venue scout-verified scores for US college sports (NCAA Football and Basketball).
**Is there a free trial, and what does it include?**
Yes. There are two free access tiers — 60-second delayed and real-time. Both cover World Cup and International Friendlies data at no cost with no rate limits. The feed includes live scores, match events (goals, cards, substitutions), scheduling, and odds data via the StablePrice feed.
View the full breakdown in our [Subscription Tiers Section](https://www.google.com/search?q=%23pricing-section) above.
**What data can I access?** Depending on your subscription: fixtures, live scores, match events, odds, historical data, real-time updates, and on-chain settlement information.
**How is data delivered?** Via a REST API and Server-Sent Events (SSE) for real-time streaming. Historical data is available through snapshot and replay endpoints.
**What is the difference between 60-second delayed and real-time data?**
60-Second Delayed: A budget-friendly, lower-cost option designed for latency-tolerant applications.
Real-Time: Premium, sub-second live data required for live odds, in-play markets, and immediate settlement.
**What is on-chain verification and why does it matter?**
Every data update is cryptographically hashed and its Merkle root is published to Solana. This lets you independently verify that a score, stat, or odds figure was published at an exact timestamp and hasn't been altered—providing your users with complete cryptographic proof. Ultimately, it eliminates data tampering and provides the unshakeable foundation needed for trustless, automated smart-contract settlement.
## Subscriptions & Pricing
**How do subscriptions work? Can I choose specific leagues?**
Subscriptions are priced per 28-day period, purchasable in multiples up to 12 months. Yes, you can skip standard bundles and select specific competitions via custom league subscriptions.
Customize your package in our Subscription Tiers Section above.
**Can I upgrade from the free tier to a paid tier?** Yes, at any time. New subscriptions take effect immediately.
**What happens if I don't renew?** API access expires at the end of the subscription period. Re-subscribe at any time to restore access.
**Where can I get help?**
* **Documentation:** Full API reference at [txline-docs.txodds.com](http://txline-docs.txodds.com).
* **General Help / Community Chat:** Email us at [hello@txodds.com](mailto:hello@txodds.com) or join our [developer community channel](https://discord.com/invite/txodds).
# Terms and Conditions
Source: https://txline-docs.txodds.com/documentation/legal/terms-and-conditions
Terms and conditions for using the TxLINE API
# Terms and Conditions
## 1. Introduction
**1.1** These Terms and Conditions ("Terms") govern access to and use of the Services made available by TXODDS.
**1.2** By acquiring, holding, accessing or using TxLINE, the Services, APIs or Data, the User agrees to be bound by these Terms.
**1.3** The Services are made available solely for business and commercial use. Consumer, personal or domestic use is prohibited.
## 2. Definitions
**"API"** means the application programming interface made available by TXODDS.
**"Data"** means all sports data, odds data, market data, analytics, statistics, metadata, pricing information, outputs, feeds, compilations and related content made available through the Services.
**"Feedback"** means all comments, ideas, enhancement requests, suggestions, derivative concepts, recommendations, corrections or other feedback relating to the Services, Data, APIs or TxLINE.
**"Services"** means the APIs, web viewers, software, infrastructure, feeds, analytics and related services provided by TXODDS.
**"TxLINE"** means the proprietary closed-loop digital access mechanism used solely to access the Services within the TXODDS ecosystem.
**"User"** means any person or entity accessing or using the Services, Data or TxLINE.
## 3. Services
**3.1** TXODDS provides proprietary sports data infrastructure and related Services.
**3.2** The Services may include:
* (a) live or delayed sports data;
* (b) odds and pricing information;
* (c) sports analytics;
* (d) APIs and developer infrastructure;
* (e) web-based access tools; and
* (f) related data products and infrastructure.
**3.3** TXODDS may modify, suspend, replace, discontinue or update any aspect of the Services, APIs, Data, schemas, formats, taxonomies, competitions, markets, infrastructure or delivery methods at any time.
**3.4** Unless expressly agreed otherwise in writing, no service level agreement, uptime commitment, guaranteed latency commitment or guaranteed availability obligation applies.
## 4. TxLINE
**4.1** TxLINE is a proprietary digital access mechanism solely enabling access to Services made available by TXODDS.
**4.2** TxLINE:
* (a) may only be used within the TXODDS ecosystem;
* (b) does not provide ownership rights, governance rights, dividends or profit participation; and
* (c) is not redeemable for fiat currency, cryptocurrency or any other asset except where required by applicable law.
**4.3** TXODDS may modify, suspend, invalidate, discontinue or replace TxLINE at any time.
**4.4** TxLINE is personal to the User and may not be sold, assigned, transferred, sublicensed, pledged, traded or otherwise made available to any third party.
**4.5** Any purported transfer of TxLINE shall be void.
## 5. Licence
**5.1** Subject to compliance with these Terms, TXODDS grants the User a limited, revocable, non-exclusive, non-transferable and non-sublicensable licence to access and use the Services solely for the User's internal business purposes.
**5.2** No ownership rights are transferred to the User.
**5.3** All rights not expressly granted are reserved by TXODDS.
## 6. Acceptable Use
**6.1** The User shall not:
* (a) resell, redistribute, sublicense or commercially exploit the Services or Data except as expressly authorised;
* (b) publish or disseminate Data publicly;
* (c) create competing services, products or databases;
* (d) reverse engineer, decompile or derive source data, methodologies or structures;
* (e) scrape or harvest Data outside authorised API functionality;
* (f) circumvent technical controls, usage limits or rate limits;
* (g) use the Services or Data for unlawful, sanctioned or fraudulent purposes;
* (h) use shared access, proxy access or pass-through access arrangements;
* (i) cache or mirror Data except as expressly authorised;
* (j) remove proprietary notices;
* (k) use the Services or Data in a manner which may expose TXODDS to legal, regulatory or reputational risk; or
* (l) use the Services or Data in connection with unlawful gambling, wagering or betting activity.
## 7. Sports Data Acknowledgements
**7.1** The User acknowledges and agrees that:
* (a) sports data is inherently dynamic and may contain delays, interruptions, inaccuracies, omissions, corrections or amendments;
* (b) sporting events, fixtures, participants, prices, scores, statistics and related information may change rapidly and without notice;
* (c) Data may be sourced from third-party providers, automated systems, proprietary models, public sources or manual inputs; and
* (d) the timing, sequencing, completeness and accuracy of Data may vary.
**7.2** The User acknowledges that:
* (a) sporting events may be suspended, abandoned, delayed, amended or cancelled;
* (b) Data feeds may be interrupted, corrected, delayed or withdrawn;
* (c) third-party suppliers may discontinue or modify source data; and
* (d) TXODDS may modify or replace Data sources, methodologies or infrastructure at any time.
## 8. Access Basis
**8.1** The Services are provided for informational and infrastructure access purposes only.
**8.2** The User uses the Services and Data entirely at its own risk.
**8.3** The User is solely responsible for independently assessing the suitability, reliability and accuracy of the Services and Data.
**8.4** TXODDS is not responsible for any decisions made by the User or any third party based on the Services and/or Data.
**8.5** The User acknowledges that fees are payable for access to the Services, APIs and infrastructure made available by TXODDS and not for guaranteed receipt, continuity, availability, accuracy or delivery of any particular Data output, event coverage or informational result.
**8.6** Except to the extent expressly required by non-excludable law, TXODDS shall have no obligation to provide refunds, credits, compensation or other remedies arising from:
* (a) interruptions;
* (b) outages;
* (c) latency;
* (d) degraded performance;
* (e) inaccuracies;
* (f) withdrawal of Data;
* (g) suspension of Services; or
* (h) modifications to the Services.
## 9. Compliance Controls
**9.1** TXODDS may, at any time and in its sole discretion:
* (a) reject, suspend, freeze, delay or cancel transactions;
* (b) refuse acquisition or use of TxLINE;
* (c) require identity verification, KYC, source of funds or other compliance information;
* (d) conduct sanctions screening, wallet screening and blockchain analytics;
* (e) impose transaction limits, usage limits or enhanced compliance requirements;
* (f) restrict access from jurisdictions, wallets or categories of users;
* (g) throttle or suspend usage;
* (h) suspend or terminate access pending compliance review; and
* (i) report information where reasonably considered necessary for legal, regulatory, sanctions, AML, fraud prevention or compliance purposes.
**9.2** The User represents and warrants that:
* (a) it is not subject to sanctions or trade restrictions; and
* (b) it shall comply with all applicable laws and regulations.
## 10. Intellectual Property
**10.1** All intellectual property rights in the Services, Data, APIs, TxLINE, software, systems, analytics, methodologies, compilations, outputs and related materials remain vested exclusively in TXODDS and its licensors.
**10.2** No implied licences are granted.
**10.3** The User acknowledges that unauthorised use or disclosure of the Services or Data may cause irreparable harm to TXODDS for which damages alone may not be an adequate remedy and TXODDS shall be entitled to seek injunctive or equitable relief.
## 11. Feedback
**11.1** All Feedback shall become the sole and exclusive property of TXODDS immediately upon creation.
**11.2** The User irrevocably assigns to TXODDS all rights, title and interest in and to Feedback and waives all moral rights to the maximum extent permitted by law.
**11.3** TXODDS may use, commercialise, modify and exploit Feedback without restriction or compensation.
## 12. Disclaimer of Warranties
**12.1** THE SERVICES, DATA, APIS AND TXLINE ARE PROVIDED "AS IS" AND "AS AVAILABLE".
**12.2** TO THE MAXIMUM EXTENT PERMITTED BY LAW, TXODDS DISCLAIMS ALL WARRANTIES, REPRESENTATIONS AND CONDITIONS, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AVAILABILITY, ACCURACY, LATENCY, PERFORMANCE OR ERROR-FREE OPERATION.
## 13. Limitation of Liability
**13.1** Nothing in these Terms excludes or limits liability which cannot lawfully be excluded or limited, including liability for:
* (a) fraud or fraudulent misrepresentation; or
* (b) death or personal injury caused by negligence.
**13.2** Subject to clause 13.1 and to the maximum extent permitted by law:
* (a) TXODDS shall not be liable for any indirect, incidental, special, consequential, exemplary or punitive losses;
* (b) TXODDS shall not be liable for loss of profits, loss of business, loss of opportunity, loss of revenue, loss of data, loss of goodwill, trading losses, betting losses or regulatory fines;
* (c) TXODDS shall not be liable for interruptions, delays, inaccuracies, omissions, degraded performance or unavailability of the Services or Data;
* (d) TXODDS shall not be liable for third-party supplier failures, telecommunications failures, blockchain failures, wallet failures, cyberattacks, internet outages or force majeure events; and
* (e) TXODDS' total aggregate liability arising out of or in connection with the Services, Data, TxLINE or these Terms shall not exceed the greater of:
* (i) the fees paid by the User to TXODDS during the twelve months preceding the relevant claim; or
* (ii) USD \$1,000.
**13.3** The User acknowledges that the pricing and commercial terms reflect the allocation of risk contained in these Terms.
## 14. Indemnity
**14.1** The User shall indemnify, defend and hold harmless TXODDS and its affiliates from and against all claims, liabilities, losses, damages, costs and expenses arising from:
* (a) the User's breach of these Terms;
* (b) misuse of the Services, Data or TxLINE;
* (c) violation of laws or regulations;
* (d) betting, trading or commercial activities;
* (e) redistribution or unauthorised disclosure of Data; or
* (f) infringement of third-party rights.
## 15. Confidentiality
**15.1** The User shall keep confidential all non-public information relating to TXODDS, the Services, APIs, Data, pricing, methodologies and systems.
**15.2** The User shall not disclose such information except where required by law.
## 16. Taxes
**16.1** The User is solely responsible for determining and paying all taxes, duties, levies or governmental charges arising from acquisition, holding, use or redemption of TxLINE or use of the Services.
**16.2** All amounts payable are exclusive of taxes unless expressly stated otherwise.
## 17. Suspension and Termination
**17.1** TXODDS may suspend or terminate access immediately where:
* (a) the User breaches these Terms;
* (b) TXODDS suspects fraud, sanctions concerns or unlawful activity;
* (c) TXODDS believes continued access may expose TXODDS to legal, regulatory, reputational or operational risk; or
* (d) suspension is reasonably considered necessary for compliance purposes.
**17.2** Upon termination:
* (a) all licences granted to the User immediately cease;
* (b) the User shall cease all use of the Services and Data; and
* (c) TXODDS may disable access and invalidate TxLINE.
## 18. Force Majeure
**18.1** TXODDS shall not be liable for delays or failures caused by events beyond its reasonable control including internet outages, supplier failures, cyberattacks, sanctions, acts of government, blockchain failures or force majeure events.
## 19. Relationship of the Parties
**19.1** Nothing in these Terms creates any partnership, joint venture, fiduciary, agency or employment relationship between the parties.
## 20. Assignment
**20.1** The User may not assign or transfer any rights or obligations under these Terms without prior written consent from TXODDS.
**20.2** TXODDS may assign or transfer its rights and obligations freely.
## 21. Evidence
**21.1** TXODDS' systems, records, logs and technical data shall constitute prima facie evidence of usage, transactions, access activity and operational matters relating to the Services and TxLINE.
## 22. Survival
**22.1** Clauses relating to intellectual property, feedback, confidentiality, indemnities, limitations of liability, taxes, compliance obligations and any provisions intended by their nature to survive termination shall survive termination or expiry of these Terms.
## 23. Governing Law
**23.1** These Terms shall be governed by and construed in accordance with the laws of England and Wales.
**23.2** The courts of England and Wales shall have exclusive jurisdiction.
## 24. General
**24.1** If any provision is held invalid or unenforceable, the remaining provisions shall remain in full force and effect.
**24.2** TXODDS may amend these Terms from time to time and any continued use of the Service shall be a deemed acceptance of any such changes.
**24.3** No waiver by TXODDS shall be effective unless in writing.
**24.4** Failure or delay by TXODDS in exercising any right shall not constitute a waiver.
**24.5** These Terms constitute the entire agreement between the parties relating to their subject matter.
**24.6** For the purpose of these Terms any reference to TXODDS means TXODDS SERVICES, LLC an Illinois limited liability company.
# StablePrice Feed
Source: https://txline-docs.txodds.com/documentation/odds/odds-coverage
Leagues covered by the odds feed
## Available Coverage
StablePrice odds coverage currently includes:
* **Soccer**: supported leagues are listed in the downloadable CSV below.
* **NCAAB (College Basketball)**: competition ID `300043`.
* **NCAAF (College Football)**: competition IDs `550001`, `10005930`, `500005`, and `10005302`.
Available markets are returned by the odds API for each covered fixture. Do not assume that a market such as both-teams-to-score, cards, corners, bookings, or player props is available unless it appears in the odds response for that fixture and network.
For each fixture, inspect the returned `SuperOddsType` and market parameters from `/api/odds/snapshot/{fixtureId}` or `/api/odds/updates/...`. The competition coverage list tells you which competitions can be covered; the odds response tells you which markets are actually available for a specific fixture.
## Market Availability
### Soccer
Complete list of all supported soccer leagues
Soccer market availability can vary by fixture and feed state. Common core markets may include result, handicap, and totals-style markets when returned by the API, but integrations should branch from the actual odds payload instead of hard-coding an assumed market catalog.
### NCAAB (College Basketball)
| Competition ID | Coverage |
| -------------- | ------------------------------- |
| 300043 | All NCAA Basketball conferences |
### NCAAF (College Football)
| Competition ID | League Name |
| -------------- | ------------------- |
| 550001 | NCAA Division I FCS |
| 10005930 | NCAA Extra Matches |
| 500005 | NCAA Division I FBS |
| 10005302 | NCAA Division I (W) |
# Overview
Source: https://txline-docs.txodds.com/documentation/odds/overview
High-fidelity consensus sports pricing powered by TxODDS and anchored on Solana
TxLINE odds are powered by Stable Price, TxODDS' consensus pricing engine, and published to Solana. Every data point is cryptographically verifiable on-chain, allowing you to audit any price at any time with no intermediary required.
Stable Price aggregates lines across global operators, including sharp books absent from standard Western feeds. The engine runs defensive logic to filter outliers, stale lines, and bad data before it ever reaches your application.
## Access & Onboarding
Access is entirely permissionless. Pay in TxL to unlock your throughput tier, and generate an API key instantly. Frictionless access to fast, verifiable data.
***
## Feature Matrix
Aggregated odds from the world's most influential and sharp bookmakers.
Built-in de-margining and outlier filtering to protect your market-making.
On-chain anchored records for trustless verification and historic backtesting.
60-second batch updates (Build tier) or sub-second real-time streams (Scale tier).
**Looking for integration specs?** Jump straight to the [Odds API Reference](/api-reference/odds) to view schemas for full fixture lifecycles and suspension handling.
# Program Addresses
Source: https://txline-docs.txodds.com/documentation/programs/addresses
TxLINE Solana program addresses and public validation accounts
## Mainnet Addresses
| Type | Address |
| -------------- | ---------------------------------------------- |
| Program ID | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` |
| TxL Token Mint | `Zhw9TVKp68a1QrftncMSd6ELXKDtpVMNuMGr1jNwdeL` |
| API Endpoint | `https://txline.txodds.com/api/` |
## Devnet Addresses
| Type | Address |
| -------------- | ---------------------------------------------- |
| Program ID | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` |
| TxL Token Mint | `4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG` |
| API Endpoint | `https://txline-dev.txodds.com/api/` |
Use all values from one network only. A devnet subscribe transaction from `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` must be activated with `https://txline-dev.txodds.com`, and a mainnet subscribe transaction from `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` must be activated with `https://txline.txodds.com`.
## Network Consistency Checklist
| Network | Solana RPC | Program ID | TxL Mint | Guest JWT URL | Activation URL |
| ------- | ------------------------------------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
| Mainnet | `https://api.mainnet-beta.solana.com` | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` | `Zhw9TVKp68a1QrftncMSd6ELXKDtpVMNuMGr1jNwdeL` | `https://txline.txodds.com/auth/guest/start` | `https://txline.txodds.com/api/token/activate` |
| Devnet | `https://api.devnet.solana.com` | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` | `4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG` | `https://txline-dev.txodds.com/auth/guest/start` | `https://txline-dev.txodds.com/api/token/activate` |
The transaction signature, guest JWT, activation endpoint, and program ID must all come from the same row. If any one value comes from a different row, activation can fail even when the on-chain transaction itself confirmed.
## API Hosts
| Network | Guest Auth | API Base |
| ------- | ------------------------------------------------ | ------------------------------------ |
| Mainnet | `https://txline.txodds.com/auth/guest/start` | `https://txline.txodds.com/api/` |
| Devnet | `https://txline-dev.txodds.com/auth/guest/start` | `https://txline-dev.txodds.com/api/` |
Use the host root for `/auth/guest/start`, then use the matching `/api/token/activate` endpoint after the on-chain `subscribe` transaction confirms.
## Program References
| Network | Reference |
| ------- | -------------------------------------------------------------- |
| Mainnet | [Program Reference (Mainnet)](/documentation/programs/mainnet) |
| Devnet | [Program Reference (Devnet)](/documentation/programs/devnet) |
For runnable code, use the examples that match your network and keep the program ID, generated types, API host, and proof data aligned.
## Activation Message
After `subscribe(serviceLevelId, durationWeeks)` confirms, activate the API token by signing this exact message with the same wallet that submitted the transaction:
```text theme={null}
${txSig}:${selectedLeagues.join(",")}:${jwt}
```
For the standard free bundle, `selectedLeagues = []`, so the message is:
```text theme={null}
${txSig}::${jwt}
```
Send the detached wallet signature as base64 in `walletSignature`, and send the guest JWT from the matching network as `Authorization: Bearer `.
## Public Validation Accounts
| Account | Seed(s) | Purpose |
| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------- |
| Daily scores roots | `daily_scores_roots`, `epochDay` as u16 little-endian | On-chain root account used for score proof validation |
| Daily batch roots | `daily_batch_roots`, `epochDay` as u16 little-endian | On-chain root account used for odds proof validation |
| Ten daily fixtures roots | `ten_daily_fixtures_roots`, aligned epoch day as u16 little-endian | On-chain root account used for fixture proof validation |
Derive the epoch day from the exact timestamp in the proof response, never from `Date.now()`. For scores, use `validation.summary.updateStats.minTimestamp`; for fixtures, use `validation.snapshot.Ts`; for odds, use `validation.odds.Ts`. Recompute it for every proof.
```typescript theme={null}
import { PublicKey } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
const programId = new PublicKey("9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA");
// For devnet, replace programId with:
// 6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J
function epochDayFromProofTimestamp(proofTimestampMs: number): number {
if (!Number.isSafeInteger(proofTimestampMs) || proofTimestampMs < 0) {
throw new Error("Expected a non-negative proof timestamp in milliseconds");
}
const epochDay = Math.floor(proofTimestampMs / 86400000);
if (epochDay > 0xffff) {
throw new Error("Proof timestamp is outside the u16 epoch-day range");
}
return epochDay;
}
function deriveDailyValidationPda(
seed: "daily_scores_roots" | "daily_batch_roots",
proofTimestampMs: number
): PublicKey {
const epochDay = epochDayFromProofTimestamp(proofTimestampMs);
return PublicKey.findProgramAddressSync(
[Buffer.from(seed), new BN(epochDay).toArrayLike(Buffer, "le", 2)],
programId
)[0];
}
function deriveTenDailyFixturesPda(fixtureProofTimestampMs: number): PublicKey {
const epochDay = epochDayFromProofTimestamp(fixtureProofTimestampMs);
const alignedEpochDay = Math.floor(epochDay / 10) * 10;
return PublicKey.findProgramAddressSync(
[
Buffer.from("ten_daily_fixtures_roots"),
new BN(alignedEpochDay).toArrayLike(Buffer, "le", 2),
],
programId
)[0];
}
```
# Program Reference (Devnet)
Source: https://txline-docs.txodds.com/documentation/programs/devnet
Public devnet integration values for TxLINE programs
## Overview
Use this page for the public devnet values needed by TxLINE integrations. Keep the Solana RPC, program ID, TxL mint, guest JWT host, activation endpoint, and API host on the same network.
Do not activate a devnet transaction on the mainnet API host. A devnet subscription transaction must be activated with `https://txline-dev.txodds.com`.
## Devnet Values
| Type | Value |
| -------------- | -------------------------------------------------- |
| Solana RPC | `https://api.devnet.solana.com` |
| Program ID | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` |
| TxL Token Mint | `4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG` |
| Guest Auth | `https://txline-dev.txodds.com/auth/guest/start` |
| Activation | `https://txline-dev.txodds.com/api/token/activate` |
| API Base | `https://txline-dev.txodds.com/api/` |
## Activation
After `subscribe(serviceLevelId, durationWeeks)` confirms, activate the API token by signing this exact message with the same wallet that submitted the transaction:
```text theme={null}
${txSig}:${selectedLeagues.join(",")}:${jwt}
```
For the standard free bundle, `selectedLeagues = []`, so the message is:
```text theme={null}
${txSig}::${jwt}
```
Send the detached wallet signature as base64 in `walletSignature`, and send the guest JWT from the devnet host as `Authorization: Bearer `.
## Validation Accounts
| Account | Seed(s) | Used for |
| ------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| Daily scores roots | `daily_scores_roots`, `epochDay` as u16 little-endian | Score proof validation with `validateStat` or `validateStatV2` |
| Daily batch roots | `daily_batch_roots`, `epochDay` as u16 little-endian | Odds proof validation |
| Ten daily fixtures roots | `ten_daily_fixtures_roots`, aligned epoch day as u16 little-endian | Fixture proof validation |
Derive the epoch day from the exact timestamp in the proof response, never from `Date.now()`. For scores, use `validation.summary.updateStats.minTimestamp`; for fixtures, use `validation.snapshot.Ts`; for odds, use `validation.odds.Ts`. Recompute it for every proof.
```typescript theme={null}
import { PublicKey } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
const programId = new PublicKey("6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J");
function epochDayFromProofTimestamp(proofTimestampMs: number): number {
if (!Number.isSafeInteger(proofTimestampMs) || proofTimestampMs < 0) {
throw new Error("Expected a non-negative proof timestamp in milliseconds");
}
const epochDay = Math.floor(proofTimestampMs / 86400000);
if (epochDay > 0xffff) {
throw new Error("Proof timestamp is outside the u16 epoch-day range");
}
return epochDay;
}
function deriveDailyValidationPda(
seed: "daily_scores_roots" | "daily_batch_roots",
proofTimestampMs: number
): PublicKey {
const epochDay = epochDayFromProofTimestamp(proofTimestampMs);
return PublicKey.findProgramAddressSync(
[Buffer.from(seed), new BN(epochDay).toArrayLike(Buffer, "le", 2)],
programId
)[0];
}
function deriveTenDailyFixturesPda(fixtureProofTimestampMs: number): PublicKey {
const epochDay = epochDayFromProofTimestamp(fixtureProofTimestampMs);
const alignedEpochDay = Math.floor(epochDay / 10) * 10;
return PublicKey.findProgramAddressSync(
[
Buffer.from("ten_daily_fixtures_roots"),
new BN(alignedEpochDay).toArrayLike(Buffer, "le", 2),
],
programId
)[0];
}
```
## Score Validation
The public score validation endpoint supports both validation shapes:
| API request | On-chain method | Use case |
| ---------------------------------------------------------------- | ---------------- | --------------------------------------------- |
| `/scores/stat-validation?fixtureId=...&seq=...&statKey=...` | `validateStat` | Single-stat or legacy two-stat validation |
| `/scores/stat-validation?fixtureId=...&seq=...&statKeys=1,2,...` | `validateStatV2` | Multi-stat validation with indexed strategies |
Use a real `seq` value from an observed score record. For V2 validation, keep the requested `statKeys` order stable because strategy indexes refer to those same positions.
## Related Guides
* [Quickstart](/documentation/quickstart)
* [On-Chain Validation](/documentation/examples/onchain-validation)
* [Runnable Devnet Examples](/documentation/examples/devnet-examples)
* [Troubleshooting](/documentation/examples/troubleshooting)
# Program Reference (Mainnet)
Source: https://txline-docs.txodds.com/documentation/programs/mainnet
Public mainnet integration values for TxLINE programs
## Overview
Use this page for the public mainnet values needed by TxLINE integrations. Keep the Solana RPC, program ID, TxL mint, guest JWT host, activation endpoint, and API host on the same network.
Do not activate a mainnet transaction on the devnet API host. A mainnet subscription transaction must be activated with `https://txline.txodds.com`.
## Mainnet Values
| Type | Value |
| -------------- | ---------------------------------------------- |
| Solana RPC | `https://api.mainnet-beta.solana.com` |
| Program ID | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` |
| TxL Token Mint | `Zhw9TVKp68a1QrftncMSd6ELXKDtpVMNuMGr1jNwdeL` |
| Guest Auth | `https://txline.txodds.com/auth/guest/start` |
| Activation | `https://txline.txodds.com/api/token/activate` |
| API Base | `https://txline.txodds.com/api/` |
## Activation
After `subscribe(serviceLevelId, durationWeeks)` confirms, activate the API token by signing this exact message with the same wallet that submitted the transaction:
```text theme={null}
${txSig}:${selectedLeagues.join(",")}:${jwt}
```
For the standard free bundle, `selectedLeagues = []`, so the message is:
```text theme={null}
${txSig}::${jwt}
```
Send the detached wallet signature as base64 in `walletSignature`, and send the guest JWT from the mainnet host as `Authorization: Bearer `.
## Validation Accounts
| Account | Seed(s) | Used for |
| ------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| Daily scores roots | `daily_scores_roots`, `epochDay` as u16 little-endian | Score proof validation with `validateStat` or `validateStatV2` |
| Daily batch roots | `daily_batch_roots`, `epochDay` as u16 little-endian | Odds proof validation |
| Ten daily fixtures roots | `ten_daily_fixtures_roots`, aligned epoch day as u16 little-endian | Fixture proof validation |
Derive the epoch day from the exact timestamp in the proof response, never from `Date.now()`. For scores, use `validation.summary.updateStats.minTimestamp`; for fixtures, use `validation.snapshot.Ts`; for odds, use `validation.odds.Ts`. Recompute it for every proof.
```typescript theme={null}
import { PublicKey } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
const programId = new PublicKey("9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA");
function epochDayFromProofTimestamp(proofTimestampMs: number): number {
if (!Number.isSafeInteger(proofTimestampMs) || proofTimestampMs < 0) {
throw new Error("Expected a non-negative proof timestamp in milliseconds");
}
const epochDay = Math.floor(proofTimestampMs / 86400000);
if (epochDay > 0xffff) {
throw new Error("Proof timestamp is outside the u16 epoch-day range");
}
return epochDay;
}
function deriveDailyValidationPda(
seed: "daily_scores_roots" | "daily_batch_roots",
proofTimestampMs: number
): PublicKey {
const epochDay = epochDayFromProofTimestamp(proofTimestampMs);
return PublicKey.findProgramAddressSync(
[Buffer.from(seed), new BN(epochDay).toArrayLike(Buffer, "le", 2)],
programId
)[0];
}
function deriveTenDailyFixturesPda(fixtureProofTimestampMs: number): PublicKey {
const epochDay = epochDayFromProofTimestamp(fixtureProofTimestampMs);
const alignedEpochDay = Math.floor(epochDay / 10) * 10;
return PublicKey.findProgramAddressSync(
[
Buffer.from("ten_daily_fixtures_roots"),
new BN(alignedEpochDay).toArrayLike(Buffer, "le", 2),
],
programId
)[0];
}
```
## Score Validation
The public score validation endpoint supports both validation shapes:
| API request | On-chain method | Use case |
| ---------------------------------------------------------------- | ---------------- | --------------------------------------------- |
| `/scores/stat-validation?fixtureId=...&seq=...&statKey=...` | `validateStat` | Single-stat or legacy two-stat validation |
| `/scores/stat-validation?fixtureId=...&seq=...&statKeys=1,2,...` | `validateStatV2` | Multi-stat validation with indexed strategies |
Use a real `seq` value from an observed score record. For V2 validation, keep the requested `statKeys` order stable because strategy indexes refer to those same positions.
## Related Guides
* [Quickstart](/documentation/quickstart)
* [On-Chain Validation](/documentation/examples/onchain-validation)
* [Streaming Data](/documentation/examples/streaming-data)
* [Troubleshooting](/documentation/examples/troubleshooting)
# Quickstart
Source: https://txline-docs.txodds.com/documentation/quickstart
Get started with the TxLINE API in minutes
## Overview
TxLINE provides cryptographically verifiable sports data through a hybrid Solana on-chain and TxODDS off-chain system. Access fixtures, odds, and scores with time-limited API tokens secured by on-chain subscriptions.
***
## Getting Started
**Want to try for free?** Use service levels 1 or 12 for instant access with no payment required.
Choose the path that matches your use case:
* **Free tier path**: Use service levels 1 or 12. No TxL purchase is required.
* **Paid subscription path**: Continue below to purchase TxL if needed, subscribe on-chain, and activate an API token.
The snippets below show the required integration pieces. To run them in your own app, provide a Solana wallet object, use the matching TxLINE IDL/types for your network, and keep the Solana RPC, program ID, guest JWT host, and API host on the same network.
Free tiers do not require a TxL purchase, but the on-chain `subscribe` transaction still needs SOL for Solana transaction fees and any account rent. On devnet, fund your wallet with a devnet SOL airdrop before subscribing.
## Select Your Network
Pick one network and use it consistently for every step. The Solana RPC, program ID, TxL mint, guest JWT, and activation endpoint must all be on the same network.
| Network | Program ID | TxL Token Mint | Guest Auth | API Base |
| ------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------------------ |
| Mainnet | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` | `Zhw9TVKp68a1QrftncMSd6ELXKDtpVMNuMGr1jNwdeL` | `https://txline.txodds.com/auth/guest/start` | `https://txline.txodds.com/api/` |
| Devnet | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` | `4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG` | `https://txline-dev.txodds.com/auth/guest/start` | `https://txline-dev.txodds.com/api/` |
```typescript theme={null}
import * as anchor from "@coral-xyz/anchor";
import type { Txoracle } from "./types/txoracle"; // Use the matching mainnet/devnet type
import txoracleIdl from "./idl/txoracle.json"; // Use the matching mainnet/devnet IDL
import {
ASSOCIATED_TOKEN_PROGRAM_ID,
TOKEN_2022_PROGRAM_ID,
getAssociatedTokenAddressSync,
} from "@solana/spl-token";
import { Connection, PublicKey, SystemProgram } from "@solana/web3.js";
import axios from "axios";
import nacl from "tweetnacl";
const NETWORK: "mainnet" | "devnet" = "mainnet";
const CONFIG = {
mainnet: {
rpcUrl: "https://api.mainnet-beta.solana.com",
apiOrigin: "https://txline.txodds.com",
programId: new PublicKey("9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA"),
txlTokenMint: new PublicKey("Zhw9TVKp68a1QrftncMSd6ELXKDtpVMNuMGr1jNwdeL"),
},
devnet: {
rpcUrl: "https://api.devnet.solana.com",
apiOrigin: "https://txline-dev.txodds.com",
programId: new PublicKey("6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J"),
txlTokenMint: new PublicKey("4Zao8ocPhmMgq7PdsYWyxvqySMGx7xb9cMftPMkEokRG"),
},
} as const;
const { rpcUrl, apiOrigin, programId, txlTokenMint } = CONFIG[NETWORK];
const apiBaseUrl = `${apiOrigin}/api`;
const connection = new Connection(rpcUrl, "confirmed");
const provider = new anchor.AnchorProvider(connection, wallet, {
commitment: "confirmed",
});
anchor.setProvider(provider);
const program = new anchor.Program(
txoracleIdl as Txoracle,
provider
);
if (!program.programId.equals(programId)) {
throw new Error(
`Loaded IDL program ${program.programId.toBase58()} does not match ${NETWORK} program ${programId.toBase58()}`
);
}
```
Do not activate a devnet transaction on `https://txline.txodds.com`, and do not activate a mainnet transaction on `https://txline-dev.txodds.com`. Use the matching `apiOrigin` from the selected network.
The `wallet` variable is your signing wallet. In a browser app, use your wallet adapter's public key, `signTransaction`, and `signMessage` methods. In a local Anchor script, use `ANCHOR_WALLET` and `ANCHOR_PROVIDER_URL` to load the payer wallet.
For a runnable devnet version of the activation and stream flow, use the scripts in [Runnable Devnet Examples](/documentation/examples/devnet-examples). They include free-tier activation, odds and scores streams, fixture validation, and `validateStatV2` examples.
## Purchase TxL (Optional)
**Note**: Purchasing TxL tokens is optional. We offer free tiers with no payment required. View all [subscription tiers](/documentation/subscription-tiers) to see free and premium options.
In order to purchase TxL, your wallet will need to be funded with USDT. If you don't have USDT on Solana, you can swap for it using [Jupiter](https://jup.ag/) or another exchange.
TxL purchases use a 2-step process: request a quote from the backend, then verify and sign the transaction locally.
### Step 1: Request Purchase Quote
```typescript theme={null}
// Get guest JWT
const authResponse = await axios.post(`${apiOrigin}/auth/guest/start`);
const jwt = authResponse.data.token;
// Request purchase quote
const txlineAmount = 50; // Amount of TxL tokens to purchase
const quoteResponse = await fetch(`${apiBaseUrl}/guest/purchase/quote`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwt}`
},
body: JSON.stringify({
buyerPubkey: wallet.publicKey.toBase58(),
txlineAmount: txlineAmount
})
});
const quoteData = await quoteResponse.json();
console.log(`Base Cost: ${quoteData.baseUsdtCost} USDT`);
console.log(`Premium Fee: ${quoteData.feeUsdtAmount} USDT`);
console.log(`Total: ${quoteData.totalUsdtCharged} USDT`);
```
### Step 2: Verify and Sign Transaction
```typescript theme={null}
// Deserialize the transaction from the quote
const txBuffer = Buffer.from(quoteData.transactionBase64, "base64");
const transaction = anchor.web3.Transaction.from(txBuffer);
// Verify transaction safety locally (recommended)
// This ensures the transaction matches what you requested
// Sign the transaction with either a local Keypair or a wallet adapter
const signedTransaction =
"secretKey" in wallet
? (transaction.partialSign(wallet), transaction)
: await wallet.signTransaction(transaction);
// Broadcast to Solana
const txSignature = await connection.sendRawTransaction(signedTransaction.serialize(), {
skipPreflight: false,
preflightCommitment: "confirmed"
});
// Confirm transaction
await connection.confirmTransaction(txSignature, "confirmed");
console.log("Purchase successful:", txSignature);
```
TxODDS may refuse purchase requests and ask for KYC (Know Your Customer) verification in accordance with compliance requirements.
## Subscribe On-Chain
Subscribe to TxLINE on-chain after choosing a service level. Paid tiers require TxL; the free tiers (service levels 1 and 12) do not require a TxL purchase. Choose between a standard subscription or a custom league selection.
Derive the shared accounts once before using either subscription tab:
```typescript theme={null}
const [tokenTreasuryPda] = PublicKey.findProgramAddressSync(
[Buffer.from("token_treasury_v2")],
program.programId
);
const tokenTreasuryVault = getAssociatedTokenAddressSync(
txlTokenMint,
tokenTreasuryPda,
true,
TOKEN_2022_PROGRAM_ID,
ASSOCIATED_TOKEN_PROGRAM_ID
);
const [pricingMatrixPda] = PublicKey.findProgramAddressSync(
[Buffer.from("pricing_matrix")],
program.programId
);
const userTokenAccount = getAssociatedTokenAddressSync(
txlTokenMint,
provider.wallet.publicKey,
false,
TOKEN_2022_PROGRAM_ID,
ASSOCIATED_TOKEN_PROGRAM_ID
);
```
```typescript theme={null}
const SERVICE_LEVEL_ID = 1;
const DURATION_WEEKS = 4;
const SELECTED_LEAGUES: number[] = []; // Standard bundle
const txSig = await program.methods
.subscribe(SERVICE_LEVEL_ID, DURATION_WEEKS)
.accounts({
user: provider.wallet.publicKey,
pricingMatrix: pricingMatrixPda,
tokenMint: txlTokenMint,
userTokenAccount,
tokenTreasuryVault,
tokenTreasuryPda,
tokenProgram: TOKEN_2022_PROGRAM_ID,
associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
systemProgram: SystemProgram.programId,
})
.rpc();
```
```typescript theme={null}
const SERVICE_LEVEL_ID = 3;
const DURATION_WEEKS = 4;
const SELECTED_LEAGUES = [500001]; // Your league IDs
const txSig = await program.methods
.subscribe(SERVICE_LEVEL_ID, DURATION_WEEKS)
.accounts({
user: provider.wallet.publicKey,
pricingMatrix: pricingMatrixPda,
tokenMint: txlTokenMint,
userTokenAccount,
tokenTreasuryVault,
tokenTreasuryPda,
tokenProgram: TOKEN_2022_PROGRAM_ID,
associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
systemProgram: SystemProgram.programId,
})
.rpc();
```
## Activate Your API Token
After subscribing on-chain, activate your API access by signing the transaction and calling the activation endpoint.
```typescript theme={null}
// Get guest JWT
const authResponse = await axios.post(`${apiOrigin}/auth/guest/start`);
const jwt = authResponse.data.token;
// Sign the subscription transaction
const messageString = `${txSig}:${SELECTED_LEAGUES.join(",")}:${jwt}`;
const message = new TextEncoder().encode(messageString);
// For SELECTED_LEAGUES = [], this signs `${txSig}::${jwt}`.
async function signActivationMessage(message: Uint8Array): Promise {
if ("signMessage" in wallet && wallet.signMessage) {
return wallet.signMessage(message);
}
const localPayer = (provider.wallet as anchor.Wallet & {
payer?: anchor.web3.Keypair;
}).payer;
if (localPayer) {
return nacl.sign.detached(message, localPayer.secretKey);
}
throw new Error("Wallet must support signMessage, or run with a local Anchor payer.");
}
const signatureBytes = await signActivationMessage(message);
const walletSignature = Buffer.from(signatureBytes).toString("base64");
// Activate API access
const activationResponse = await axios.post(
`${apiBaseUrl}/token/activate`,
{
txSig,
walletSignature,
leagues: SELECTED_LEAGUES,
},
{ headers: { Authorization: `Bearer ${jwt}` } }
);
const apiToken = activationResponse.data.token || activationResponse.data;
```
The activation signature must be a base64-encoded detached wallet signature over the exact message string. For the standard free bundle, `SELECTED_LEAGUES = []`, so the message has two colons between `txSig` and `jwt`:
```text theme={null}
${txSig}::${jwt}
```
The signing wallet must be the same wallet that submitted the on-chain `subscribe` transaction, and the `jwt` must come from the same network host used for activation.
You're now ready to use the API. Send both activated credentials with data API requests:
| Header | Value |
| --------------- | -------------------------------------------- |
| `Authorization` | `Bearer ${jwt}` from `/auth/guest/start` |
| `X-Api-Token` | `apiToken` returned by `/api/token/activate` |
## Credential Lifecycle
| Credential | Where it comes from | How it is used |
| ---------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Guest JWT | `POST /auth/guest/start` on the matching host | Sent as `Authorization: Bearer ` and included in the activation signature preimage |
| API token | `POST /api/token/activate` after a confirmed `subscribe` transaction | Sent as `X-Api-Token` on data requests |
If a data request returns `401`, renew the guest JWT from the same network host and retry with the same activated API token. If activation returns `403`, check the signed message, wallet, signature encoding, transaction network, and activation host.
## Next Steps
* View the complete [API Reference](/api-reference/authentication/start-a-new-guest-session) to explore all available endpoints
* Check out [Subscription Tiers](/documentation/subscription-tiers) for pricing and plan options
* Run the [Runnable Devnet Examples](/documentation/examples/devnet-examples) for end-to-end devnet activation, streaming, and validation
* Use [Troubleshooting](/documentation/examples/troubleshooting) to diagnose activation, streaming, and validation errors
# Basketball Feed
Source: https://txline-docs.txodds.com/documentation/scores/basketball-feed
TxODDS US Basketball Feed documentation
## Coverage
Basketball score encodings and feed semantics are documented below. Use the shared [Schedule](/documentation/scores/schedule) and fixtures snapshot API for current basketball fixture availability.
## On-Chain Specifications
These specifications define how basketball game phases and statistics are encoded for on-chain operations, including cryptographic validation and trading settlement.
### Game Phase Encoding
| Name | ID | Description | Competition Type |
| ---- | -- | -------------------- | ---------------- |
| NS | 1 | Not started | All |
| Q1 | 2 | Quarter 1 | NBA |
| Q1B | 3 | Quarter 1 break | NBA |
| Q2 | 4 | Quarter 2 | NBA |
| HT | 5 | Halftime | All |
| Q3 | 6 | Quarter 3 | NBA |
| Q3B | 7 | Quarter 3 break | NBA |
| Q4 | 8 | Quarter 4 | NBA |
| F | 9 | Ended | All |
| WO | 10 | Waiting for Overtime | All |
| OT | 11 | Overtime | All |
| OB | 12 | Overtime Break | All |
| FO | 13 | Ended after Overtime | All |
| H1 | 19 | First half | NCAA |
| H2 | 20 | Second half | NCAA |
### Stat Period Encoding
Stats are encoded with a formula: `(half * 1000 OR quarter * 10000) + base_key`
These encodings are used for on-chain validation proofs and trading settlement.
**Full Game Stats (Keys 1-36):**
| Key | Statistic |
| --- | ---------------------------------------- |
| 1 | Participant 1 Total Score |
| 2 | Participant 2 Total Score |
| 3 | Participant 1 Total Fouls |
| 4 | Participant 2 Total Fouls |
| 5 | Participant 1 Total Personal Fouls |
| 6 | Participant 2 Total Personal Fouls |
| 7 | Participant 1 Total Blocks |
| 8 | Participant 2 Total Blocks |
| 9 | Participant 1 Total Rebounds |
| 10 | Participant 2 Total Rebounds |
| 11 | Participant 1 Total free throws made |
| 12 | Participant 2 Total free throws made |
| 13 | Participant 1 Total 2-points made |
| 14 | Participant 2 Total 2-points made |
| 15 | Participant 1 Total 3-points made |
| 16 | Participant 2 Total 3-points made |
| 17 | Participant 1 Total free throws missed |
| 18 | Participant 2 Total free throws missed |
| 19 | Participant 1 Total 2-points missed |
| 20 | Participant 2 Total 2-points missed |
| 21 | Participant 1 Total 3-points missed |
| 22 | Participant 2 Total 3-points missed |
| 23 | Participant 1 Total free throws attempts |
| 24 | Participant 2 Total free throws attempts |
| 25 | Participant 1 Total 2-points attempts |
| 26 | Participant 2 Total 2-points attempts |
| 27 | Participant 1 Total 3-points attempts |
| 28 | Participant 2 Total 3-points attempts |
| 29 | Participant 1 Total Assists |
| 30 | Participant 2 Total Assists |
| 31 | Participant 1 Total Turnovers |
| 32 | Participant 2 Total Turnovers |
| 33 | Participant 1 Total Steals |
| 34 | Participant 2 Total Steals |
| 35 | Participant 1 Total Used timeouts |
| 36 | Participant 2 Total Used timeouts |
**Period-Specific Stats** - Add period multiplier to base keys:
* **First Half (H1)**: Add 1000
* **Second Half (H2)**: Add 2000
* **Quarter 1**: Add 10000
* **Quarter 2**: Add 20000
* **Quarter 3**: Add 30000
* **Quarter 4**: Add 40000
**Usage:** These encodings are required when validating score data against on-chain Merkle roots, creating trading offers, or settling trades with cryptographic proofs.
## Documentation
Complete documentation for the TxODDS US Basketball data feed
# American Football Feed
Source: https://txline-docs.txodds.com/documentation/scores/football-feed
TxODDS US Football Feed documentation
## Coverage
US football score encodings and feed semantics are documented below. Use the shared [Schedule](/documentation/scores/schedule) and fixtures snapshot API for current US football fixture availability.
## On-Chain Specifications
These specifications define how football game phases and statistics are encoded for on-chain operations, including cryptographic validation and trading settlement.
### Game Phase Encoding
**Standard Phases:**
| Name | ID | Description |
| ---- | -- | --------------------- |
| NS | 1 | Not started |
| Q1 | 2 | Quarter 1 in play |
| Q1B | 3 | Quarter 1 break |
| Q2 | 4 | Quarter 2 in play |
| HT | 5 | Halftime |
| Q3 | 6 | Quarter 3 in play |
| Q3B | 7 | Quarter 3 break |
| Q4 | 8 | Quarter 4 in play |
| F | 9 | Ended (finished) |
| WO | 10 | Waiting for Overtime |
| OT | 11 | Overtime |
| OB | 12 | Overtime Break |
| FO | 13 | Ended after Overtime |
| I | 14 | Interrupted |
| A | 15 | Abandoned |
| C | 16 | Cancelled |
| TXCC | 17 | TX Coverage Cancelled |
| TXCS | 18 | TX Coverage Suspended |
**Overtime Phases:**
| Name | ID | Description |
| ---- | ---- | ------------------- |
| OT1 | 1011 | Overtime 1 |
| OB1 | 1012 | Overtime 1 break |
| OT2 | 2011 | Overtime 2 |
| OB2 | 2012 | Overtime 2 break |
| ... | ... | (continues to OT12) |
### Stat Period Encoding
Stats are encoded with a formula: `(half * 1000 OR quarter * 10000) + base_key`
These encodings are used for on-chain validation proofs and trading settlement.
**Full Game Stats (Keys 1-16):**
| Key | Statistic |
| --- | --------------------------------------------- |
| 1 | Participant 1 Total Score |
| 2 | Participant 2 Total Score |
| 3 | Participant 1 Total Touchdowns |
| 4 | Participant 2 Total Touchdowns |
| 5 | Participant 1 Total Field Goals |
| 6 | Participant 2 Total Field Goals |
| 7 | Participant 1 Total 1pt Conversions |
| 8 | Participant 2 Total 1pt Conversions |
| 9 | Participant 1 Total 2pt Conversions |
| 10 | Participant 2 Total 2pt Conversions |
| 11 | Participant 1 Total Safeties |
| 12 | Participant 2 Total Safeties |
| 13 | Participant 1 Total 1pt Safeties |
| 14 | Participant 2 Total 1pt Safeties |
| 15 | Participant 1 Total Defensive 2pt Conversions |
| 16 | Participant 2 Total Defensive 2pt Conversions |
**Period-Specific Stats** - Add period multiplier to base keys:
* **First Half (H1)**: Add 1000 (e.g., key 1001 = Participant 1 1st Half Score)
* **Second Half (H2)**: Add 2000 (e.g., key 2001 = Participant 1 2nd Half Score)
* **Quarter 1**: Add 10000 (e.g., key 10001 = Participant 1 Q1 Score)
* **Quarter 2**: Add 20000 (e.g., key 20001 = Participant 1 Q2 Score)
* **Quarter 3**: Add 30000 (e.g., key 30001 = Participant 1 Q3 Score)
* **Quarter 4**: Add 40000 (e.g., key 40001 = Participant 1 Q4 Score)
**Usage:** These encodings are required when validating score data against on-chain Merkle roots, creating trading offers, or settling trades with cryptographic proofs.
## Documentation
Complete documentation for the TxODDS US Football data feed
# Overview
Source: https://txline-docs.txodds.com/documentation/scores/overview
Cryptographically verifiable scores data for soccer, US football, and basketball
The TxLINE scores feed delivers granular sports score data that can be validated against on-chain Merkle roots. Current documentation covers soccer, US football, and basketball score encodings, with select leagues available through the free tiers.
Every supported stat is encoded with deterministic keys and published through batches whose roots are anchored on Solana. Use the feed-specific pages for stat-key encoding, and use the [Schedule](/documentation/scores/schedule) and API responses to confirm current fixture availability.
For on-chain validation, use [On-Chain Validation](/documentation/examples/onchain-validation). The current examples include both legacy `validateStat` requests and `validateStatV2` multi-stat strategies through the runnable devnet scripts in [Runnable Devnet Examples](/documentation/examples/devnet-examples).
For final match outcome settlement, scores records with `action=game_finalised` use `statusId=100` and `period=100` on the current devnet and mainnet releases. That gives integrations a single final-outcome marker independent of whether the match ended in regulation, extra time, penalties, or abandonment.
| Feed | What to use |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| Soccer | [Soccer Feed](/documentation/scores/soccer-feed) for soccer stat keys and game phases |
| American football | [American Football Feed](/documentation/scores/football-feed) for US football phase and stat encodings |
| Basketball | [Basketball Feed](/documentation/scores/basketball-feed) for basketball phase and stat encodings |
## Built for Settlement & Micro-Markets
This feed is built for applications that need deterministic event data and proof-based settlement.
* **Deterministic Encoding:** Every stat maps to a fixed cryptographic key with period multipliers applied on top.
* **Reliable Proofs:** If you are building automated smart contract settlement logic or validation proofs, the exact layout schemas are defined in the technical specifications below.
* **Network-Aware Access:** Use mainnet credentials with mainnet APIs and devnet credentials with devnet APIs.
## Technical Capabilities
Direct-from-stadium collection removes broadcast lag and delay vulnerabilities.
Fixed-key encoding tailored for programmatic trade settlement and smart contracts.
Redundant infrastructure engineered for zero data loss during peak tournament events.
If a live stream is connected but no data messages arrive, there may be no covered fixture actively producing updates at that moment. Check the [Schedule](/documentation/scores/schedule), keep the stream open during live windows, or use historical endpoints for completed fixtures.
# Schedule
Source: https://txline-docs.txodds.com/documentation/scores/schedule
Confirmed fixtures currently listed for TxLINE match data coverage
## NFL Preseason
### August 21, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | -------------------- | ------------------- | ------------- |
| 18086885 | US Football | USA | NFL > Preseason | 00:00 | Houston Texans | Las Vegas Raiders | TV/Stream |
| 18086887 | US Football | USA | NFL > Preseason | 02:00 | L.A. Chargers | San Francisco 49ers | TV/Stream |
| 18086881 | US Football | USA | NFL > Preseason | 23:00 | Pittsburgh Steelers | N.Y. Jets | TV/Stream |
| 18086865 | US Football | USA | NFL > Preseason | 23:30 | Jacksonville Jaguars | Carolina Panthers | TV/Stream |
### August 22, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | -------------------- | --------------------- | ------------- |
| 18086869 | US Football | USA | NFL > Preseason | 01:00 | Denver Broncos | Green Bay Packers | TV/Stream |
| 18086873 | US Football | USA | NFL > Preseason | 16:00 | Detroit Lions | Washington Commanders | TV/Stream |
| 18086871 | US Football | USA | NFL > Preseason | 17:00 | Cleveland Browns | Buffalo Bills | TV/Stream |
| 18086872 | US Football | USA | NFL > Preseason | 17:00 | Indianapolis Colts | Atlanta Falcons | TV/Stream |
| 18086883 | US Football | USA | NFL > Preseason | 17:00 | Minnesota Vikings | Baltimore Ravens | TV/Stream |
| 18086863 | US Football | USA | NFL > Preseason | 20:00 | L.A. Rams | New Orleans Saints | TV/Stream |
| 18086882 | US Football | USA | NFL > Preseason | 20:00 | Miami Dolphins | N.Y. Giants | TV/Stream |
| 18086874 | US Football | USA | NFL > Preseason | 23:00 | Cincinnati Bengals | Chicago Bears | TV/Stream |
| 18086886 | US Football | USA | NFL > Preseason | 23:00 | New England Patriots | Philadelphia Eagles | TV/Stream |
| 18086858 | US Football | USA | NFL > Preseason | 23:30 | Tampa Bay Buccaneers | Kansas City Chiefs | TV/Stream |
### August 23, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | ----------------- | -------------- | ------------- |
| 18086878 | US Football | USA | NFL > Preseason | 02:00 | Arizona Cardinals | Dallas Cowboys | TV/Stream |
### August 24, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | ---------------- | ---------------- | ------------- |
| 18086880 | US Football | USA | NFL > Preseason | 00:00 | Tennessee Titans | Seattle Seahawks | TV/Stream |
### August 27, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | ------------- | ------------------- | ------------- |
| 18086890 | US Football | USA | NFL > Preseason | 23:00 | Buffalo Bills | Pittsburgh Steelers | TV/Stream |
### August 28, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | -------------------- | --------------------- | ------------- |
| 18086860 | US Football | USA | NFL > Preseason | 00:00 | Las Vegas Raiders | San Francisco 49ers | TV/Stream |
| 18086889 | US Football | USA | NFL > Preseason | 00:00 | Cleveland Browns | New England Patriots | TV/Stream |
| 18086895 | US Football | USA | NFL > Preseason | 02:00 | L.A. Chargers | L.A. Rams | TV/Stream |
| 18086901 | US Football | USA | NFL > Preseason | 22:00 | Baltimore Ravens | Washington Commanders | TV/Stream |
| 18086891 | US Football | USA | NFL > Preseason | 23:00 | Miami Dolphins | Atlanta Falcons | TV/Stream |
| 18086894 | US Football | USA | NFL > Preseason | 23:00 | Carolina Panthers | Houston Texans | TV/Stream |
| 18086892 | US Football | USA | NFL > Preseason | 23:30 | Jacksonville Jaguars | Tampa Bay Buccaneers | TV/Stream |
### August 29, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | --------------- | ---------- | ------------------- | ------------------ | ------------- |
| 18086896 | US Football | USA | NFL > Preseason | 23:30 | N.Y. Jets | N.Y. Giants | TV/Stream |
| 18086888 | US Football | USA | NFL > Preseason | 00:00 | Kansas City Chiefs | Seattle Seahawks | TV/Stream |
| 18086893 | US Football | USA | NFL > Preseason | 00:00 | Green Bay Packers | Arizona Cardinals | TV/Stream |
| 18086897 | US Football | USA | NFL > Preseason | 00:00 | Philadelphia Eagles | Cincinnati Bengals | TV/Stream |
| 18086899 | US Football | USA | NFL > Preseason | 00:00 | Dallas Cowboys | New Orleans Saints | TV/Stream |
| 18086900 | US Football | USA | NFL > Preseason | 01:00 | Denver Broncos | Minnesota Vikings | TV/Stream |
| 18086898 | US Football | USA | NFL > Preseason | 17:00 | Indianapolis Colts | Detroit Lions | TV/Stream |
| 18094557 | US Football | USA | NFL > Preseason | 22:00 | Tennessee Titans | Chicago Bears | TV/Stream |
## NFL Regular Season
### September 10, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ---------------- | -------------------- | ------------- |
| 18041577 | US Football | USA | NFL > Regular Season | 00:20 | Seattle Seahawks | New England Patriots | TV/Stream |
### September 11, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | --------- | ------------------- | ------------- |
| 18023663 | US Football | USA | NFL > Regular Season | 00:35 | L.A. Rams | San Francisco 49ers | TV/Stream |
### September 13, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | -------------------- | --------------------- | ------------- |
| 18041414 | US Football | USA | NFL > Regular Season | 17:00 | Detroit Lions | New Orleans Saints | TV/Stream |
| 18041416 | US Football | USA | NFL > Regular Season | 17:00 | Houston Texans | Buffalo Bills | TV/Stream |
| 18041417 | US Football | USA | NFL > Regular Season | 17:00 | Tennessee Titans | N.Y. Jets | TV/Stream |
| 18041489 | US Football | USA | NFL > Regular Season | 17:00 | Carolina Panthers | Chicago Bears | TV/Stream |
| 18041490 | US Football | USA | NFL > Regular Season | 17:00 | Indianapolis Colts | Baltimore Ravens | TV/Stream |
| 18041491 | US Football | USA | NFL > Regular Season | 17:00 | Pittsburgh Steelers | Atlanta Falcons | TV/Stream |
| 18041573 | US Football | USA | NFL > Regular Season | 17:00 | Cincinnati Bengals | Tampa Bay Buccaneers | TV/Stream |
| 18041576 | US Football | USA | NFL > Regular Season | 17:00 | Jacksonville Jaguars | Cleveland Browns | TV/Stream |
| 18041415 | US Football | USA | NFL > Regular Season | 20:25 | Las Vegas Raiders | Miami Dolphins | TV/Stream |
| 18041488 | US Football | USA | NFL > Regular Season | 20:25 | L.A. Chargers | Arizona Cardinals | TV/Stream |
| 18041574 | US Football | USA | NFL > Regular Season | 20:25 | Minnesota Vikings | Green Bay Packers | TV/Stream |
| 18041575 | US Football | USA | NFL > Regular Season | 20:25 | Philadelphia Eagles | Washington Commanders | TV/Stream |
### September 14, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ----------- | -------------- | ------------- |
| 18031031 | US Football | USA | NFL > Regular Season | 00:20 | N.Y. Giants | Dallas Cowboys | TV/Stream |
### September 15, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ------------------ | -------------- | ------------- |
| 18035765 | US Football | USA | NFL > Regular Season | 00:15 | Kansas City Chiefs | Denver Broncos | TV/Stream |
### September 18, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ------------- | ------------- | ------------- |
| 18033804 | US Football | USA | NFL > Regular Season | 00:15 | Buffalo Bills | Detroit Lions | TV/Stream |
### September 20, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | -------------------- | --------------------- | ------------- |
| 18041409 | US Football | USA | NFL > Regular Season | 17:00 | Chicago Bears | Minnesota Vikings | TV/Stream |
| 18041410 | US Football | USA | NFL > Regular Season | 17:00 | Baltimore Ravens | New Orleans Saints | TV/Stream |
| 18041483 | US Football | USA | NFL > Regular Season | 17:00 | Tennessee Titans | Philadelphia Eagles | TV/Stream |
| 18041484 | US Football | USA | NFL > Regular Season | 17:00 | Houston Texans | Cincinnati Bengals | TV/Stream |
| 18041485 | US Football | USA | NFL > Regular Season | 17:00 | Tampa Bay Buccaneers | Cleveland Browns | TV/Stream |
| 18041486 | US Football | USA | NFL > Regular Season | 17:00 | New England Patriots | Pittsburgh Steelers | TV/Stream |
| 18041568 | US Football | USA | NFL > Regular Season | 17:00 | Atlanta Falcons | Carolina Panthers | TV/Stream |
| 18041569 | US Football | USA | NFL > Regular Season | 17:00 | N.Y. Jets | Green Bay Packers | TV/Stream |
| 18041411 | US Football | USA | NFL > Regular Season | 20:05 | Denver Broncos | Jacksonville Jaguars | TV/Stream |
| 18041570 | US Football | USA | NFL > Regular Season | 20:05 | L.A. Chargers | Las Vegas Raiders | TV/Stream |
| 18041413 | US Football | USA | NFL > Regular Season | 20:25 | Arizona Cardinals | Seattle Seahawks | TV/Stream |
| 18041487 | US Football | USA | NFL > Regular Season | 20:25 | San Francisco 49ers | Miami Dolphins | TV/Stream |
| 18041571 | US Football | USA | NFL > Regular Season | 20:25 | Dallas Cowboys | Washington Commanders | TV/Stream |
### September 21, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ------------------ | ------------------ | ------------- |
| 18041412 | US Football | USA | NFL > Regular Season | 00:20 | Kansas City Chiefs | Indianapolis Colts | TV/Stream |
### September 22, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | --------- | ----------- | ------------- |
| 18041572 | US Football | USA | NFL > Regular Season | 00:15 | L.A. Rams | N.Y. Giants | TV/Stream |
### September 25, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ----------------- | --------------- | ------------- |
| 18041422 | US Football | USA | NFL > Regular Season | 00:15 | Green Bay Packers | Atlanta Falcons | TV/Stream |
### September 27, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | --------------------- | -------------------- | ------------- |
| 18041423 | US Football | USA | NFL > Regular Season | 17:00 | Detroit Lions | N.Y. Jets | TV/Stream |
| 18041424 | US Football | USA | NFL > Regular Season | 17:00 | Indianapolis Colts | Houston Texans | TV/Stream |
| 18041425 | US Football | USA | NFL > Regular Season | 17:00 | Washington Commanders | Seattle Seahawks | TV/Stream |
| 18041498 | US Football | USA | NFL > Regular Season | 17:00 | Buffalo Bills | L.A. Chargers | TV/Stream |
| 18041499 | US Football | USA | NFL > Regular Season | 17:00 | Miami Dolphins | Kansas City Chiefs | TV/Stream |
| 18041500 | US Football | USA | NFL > Regular Season | 17:00 | Pittsburgh Steelers | Cincinnati Bengals | TV/Stream |
| 18041501 | US Football | USA | NFL > Regular Season | 17:00 | Jacksonville Jaguars | New England Patriots | TV/Stream |
| 18041584 | US Football | USA | NFL > Regular Season | 17:00 | Cleveland Browns | Carolina Panthers | TV/Stream |
| 18041585 | US Football | USA | NFL > Regular Season | 17:00 | N.Y. Giants | Tennessee Titans | TV/Stream |
| 18041586 | US Football | USA | NFL > Regular Season | 20:05 | San Francisco 49ers | Arizona Cardinals | TV/Stream |
| 18041587 | US Football | USA | NFL > Regular Season | 20:05 | Tampa Bay Buccaneers | Minnesota Vikings | TV/Stream |
| 18033878 | US Football | USA | NFL > Regular Season | 20:25 | Dallas Cowboys | Baltimore Ravens | TV/Stream |
| 18041426 | US Football | USA | NFL > Regular Season | 20:25 | New Orleans Saints | Las Vegas Raiders | TV/Stream |
### September 28, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | -------------- | --------- | ------------- |
| 18041502 | US Football | USA | NFL > Regular Season | 00:20 | Denver Broncos | L.A. Rams | TV/Stream |
### September 29, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ----------- | ------- | -------------------- | ---------- | ------------- | ------------------- | ------------- |
| 18041427 | US Football | USA | NFL > Regular Season | 00:15 | Chicago Bears | Philadelphia Eagles | TV/Stream |
## MLS
### August 16, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | ------------- | ---------- | -------------------- | -------------------- | ------------- |
| 17615158 | Soccer | USA | MLS | 23:30 | Toronto | New England | TV/Stream |
| 17615157 | Soccer | USA | MLS | 23:30 | Atlanta United | NY Red Bulls | TV/Stream |
| 17615188 | Soccer | USA | MLS | 23:30 | Orlando City | FC Cincinnati | TV/Stream |
| 17615189 | Soccer | USA | MLS | 23:30 | Montreal | DC United | TV/Stream |
| 17615273 | Soccer | USA | MLS | 23:30 | Charlotte | Nashville | TV/Stream |
| 17615120 | Soccer | USA | MLS | 00:30 | Nashville | Minnesota | TV/Stream |
| 17615131 | Soccer | USA | MLS | 00:30 | Houston Dynamo | LA Galaxy | TV/Stream |
| 17615130 | Soccer | USA | MLS | 01:30 | Real Salt Lake | Minnesota United | TV/Stream |
| 17615275 | Soccer | USA | MLS | 01:30 | Colorado Rapids | Sporting Kansas City | TV/Stream |
| 17615152 | Soccer | USA | MLS | 02:30 | San Jose Earthquakes | St. Louis City | TV/Stream |
| 17615191 | Soccer | USA | MLS | 02:30 | Los Angeles | Seattle | TV/Stream |
### August 17, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | ------------- | ---------- | ---------------- | ------------------- | ------------- |
| 17615190 | Soccer | USA | MLS | 22:00 | Chicago Fire | Portland Timbers | TV/Stream |
| 17615276 | Soccer | USA | MLS | 22:00 | New York City | Philadelphia Union | TV/Stream |
| 17615274 | Soccer | USA | MLS | 00:30 | Austin FC | Dallas | TV/Stream |
| 17615192 | Soccer | USA | MLS | 02:30 | Seattle Sounders | Vancouver Whitecaps | TV/Stream |
## Premier League
### August 21, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | --------- | ------------- |
| 18146819 | Soccer | England | Premier League | 19:00 | Arsenal | Coventry | TV/Stream |
### August 22, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------------- | -------------- | ------------- |
| 18146817 | Soccer | England | Premier League | 11:30 | Hull City | Manchester Utd | TV/Stream |
| 18146818 | Soccer | England | Premier League | 14:00 | Everton | Crystal Palace | TV/Stream |
| 18146823 | Soccer | England | Premier League | 14:00 | Ipswich | Sunderland | TV/Stream |
| 18146825 | Soccer | England | Premier League | 14:00 | Nottingham Forest | Leeds | TV/Stream |
| 18146827 | Soccer | England | Premier League | 16:30 | Brentford | Tottenham | TV/Stream |
### August 23, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------------- | ----------- | ------------- |
| 18146816 | Soccer | England | Premier League | 13:00 | Manchester City | Bournemouth | TV/Stream |
| 18146831 | Soccer | England | Premier League | 13:00 | Brighton | Aston Villa | TV/Stream |
| 18146832 | Soccer | England | Premier League | 15:30 | Newcastle | Liverpool | TV/Stream |
### August 24, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | --------- | ------------- |
| 18146824 | Soccer | England | Premier League | 19:00 | Fulham | Chelsea | TV/Stream |
### August 28, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | -------------- | --------------- | ------------- |
| 18146820 | Soccer | England | Premier League | 19:00 | Crystal Palace | Manchester City | TV/Stream |
### August 29, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------- | ----------------- | ------------- |
| 18146822 | Soccer | England | Premier League | 11:30 | Liverpool | Nottingham Forest | TV/Stream |
| 18146828 | Soccer | England | Premier League | 14:00 | Bournemouth | Everton | TV/Stream |
| 18146829 | Soccer | England | Premier League | 14:00 | Coventry | Hull City | TV/Stream |
| 18146834 | Soccer | England | Premier League | 16:30 | Tottenham | Newcastle | TV/Stream |
### August 30, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | -------------- | --------- | ------------- |
| 18146826 | Soccer | England | Premier League | 13:00 | Leeds | Brentford | TV/Stream |
| 18146833 | Soccer | England | Premier League | 13:00 | Chelsea | Brighton | TV/Stream |
| 18146836 | Soccer | England | Premier League | 13:00 | Sunderland | Fulham | TV/Stream |
| 18146830 | Soccer | England | Premier League | 15:30 | Manchester Utd | Ipswich | TV/Stream |
### August 31, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------- | --------- | ------------- |
| 18146821 | Soccer | England | Premier League | 19:00 | Aston Villa | Arsenal | TV/Stream |
### September 4, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | --------- | ------------- |
| 18146837 | Soccer | England | Premier League | 19:00 | Ipswich | Liverpool | TV/Stream |
### September 5, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------------- | -------------- | ------------- |
| 18146723 | Soccer | England | Premier League | 11:30 | Newcastle | Bournemouth | TV/Stream |
| 18146721 | Soccer | England | Premier League | 14:00 | Manchester City | Coventry | TV/Stream |
| 18146722 | Soccer | England | Premier League | 14:00 | Brighton | Leeds | TV/Stream |
| 18146725 | Soccer | England | Premier League | 14:00 | Nottingham Forest | Tottenham | TV/Stream |
| 18146891 | Soccer | England | Premier League | 14:00 | Brentford | Sunderland | TV/Stream |
| 18146892 | Soccer | England | Premier League | 14:00 | Fulham | Crystal Palace | TV/Stream |
| 18146724 | Soccer | England | Premier League | 16:30 | Hull City | Aston Villa | TV/Stream |
### September 6, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | -------------- | ------------- |
| 18146836 | Soccer | England | Premier League | 13:00 | Everton | Manchester Utd | TV/Stream |
| 18146720 | Soccer | England | Premier League | 15:30 | Arsenal | Chelsea | TV/Stream |
### September 12, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | -------------- | ----------------- | ------------- |
| 18146728 | Soccer | England | Premier League | 14:00 | Aston Villa | Nottingham Forest | TV/Stream |
| 18146729 | Soccer | England | Premier League | 14:00 | Crystal Palace | Ipswich | TV/Stream |
| 18146843 | Soccer | England | Premier League | 14:00 | Liverpool | Fulham | TV/Stream |
| 18146896 | Soccer | England | Premier League | 14:00 | Bournemouth | Brentford | TV/Stream |
| 18146896 | Soccer | England | Premier League | 14:00 | Chelsea | Hull City | TV/Stream |
| 18146731 | Soccer | England | Premier League | 16:30 | Tottenham | Everton | TV/Stream |
| 18146898 | Soccer | England | Premier League | 19:00 | Sunderland | Arsenal | TV/Stream |
### September 13, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | -------------- | --------------- | ------------- |
| 18146841 | Soccer | England | Premier League | 13:00 | Coventry | Brighton | TV/Stream |
| 18146730 | Soccer | England | Premier League | 15:30 | Manchester Utd | Manchester City | TV/Stream |
### September 14, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | --------- | ------------- |
| 18146897 | Soccer | England | Premier League | 19:00 | Leeds | Newcastle | TV/Stream |
### September 18, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | --------- | --------- | ------------- |
| 18146732 | Soccer | England | Premier League | 19:00 | Brentford | Chelsea | TV/Stream |
### September 19, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------------- | -------------- | ------------- |
| 18146735 | Soccer | England | Premier League | 11:30 | Tottenham | Aston Villa | TV/Stream |
| 18146733 | Soccer | England | Premier League | 14:00 | Everton | Ipswich | TV/Stream |
| 18146844 | Soccer | England | Premier League | 14:00 | Manchester Utd | Sunderland | TV/Stream |
| 18146845 | Soccer | England | Premier League | 14:00 | Leeds | Crystal Palace | TV/Stream |
| 18146899 | Soccer | England | Premier League | 14:00 | Brighton | Arsenal | TV/Stream |
| 18146901 | Soccer | England | Premier League | 14:00 | Newcastle | Hull City | TV/Stream |
| 18146850 | Soccer | England | Premier League | 16:30 | Nottingham Forest | Coventry | TV/Stream |
### September 20, 2026
| fixtureId | Sport | Country | Fixture Group | Time (UTC) | Home Team | Away Team | Coverage Type |
| --------- | ------ | ------- | -------------- | ---------- | ----------- | -------------- | ------------- |
| 18146842 | Soccer | England | Premier League | 13:00 | Bournemouth | Liverpool | TV/Stream |
| 18146847 | Soccer | England | Premier League | 15:30 | Fulham | Manchester Utd | TV/Stream |
***
# Soccer Feed
Source: https://txline-docs.txodds.com/documentation/scores/soccer-feed
TxODDS Soccer Feed documentation
Get free access to select sports with TxLINE's complimentary tiers. Real-time and 60-second delayed options available.
## Coverage
For a complete list of upcoming soccer fixtures and competitions covered by TxLINE, please refer to the [Schedule](/documentation/scores/schedule).
## On-Chain Specifications
These specifications define how soccer game phases and statistics are encoded for on-chain operations, including cryptographic validation and trading settlement.
### Game Phase Encoding
| Name | ID | Description |
| ---- | -- | ------------------------------ |
| NS | 1 | Not started |
| H1 | 2 | First half in play |
| HT | 3 | Halftime |
| H2 | 4 | Second half in play |
| F | 5 | Ended (finished) |
| WET | 6 | Waiting for Extra Time |
| ET1 | 7 | Extra Time first half in play |
| HTET | 8 | Extra Time halftime |
| ET2 | 9 | Extra Time second half in play |
| FET | 10 | Ended after Extra Time |
| WPE | 11 | Waiting for Penalty Shootout |
| PE | 12 | Penalty Shootout in progress |
| FPE | 13 | Ended after Penalty Shootout |
| I | 14 | Interrupted |
| A | 15 | Abandoned |
| C | 16 | Cancelled |
| TXCC | 17 | TX Coverage Cancelled |
| TXCS | 18 | TX Coverage Suspended |
| P | 19 | Postponed |
### Stat Period Encoding
Stats are encoded as `period_prefix + base_key`.
These encodings are used for on-chain validation proofs and trading settlement.
**Full Game Stats (Keys 1-8):**
| Key | Statistic |
| --- | -------------------------------- |
| 1 | Participant 1 Total Goals |
| 2 | Participant 2 Total Goals |
| 3 | Participant 1 Total Yellow Cards |
| 4 | Participant 2 Total Yellow Cards |
| 5 | Participant 1 Total Red Cards |
| 6 | Participant 2 Total Red Cards |
| 7 | Participant 1 Total Corners |
| 8 | Participant 2 Total Corners |
**Period Prefixes:**
| Prefix | Period | Example |
| ------ | ------- | --------------------------------------------- |
| 0 | Total | `8` = Participant 2 total corners |
| 1000 | H1 | `1001` = Participant 1 H1 goals |
| 2000 | HT | `2001` = Participant 1 halftime goals |
| 3000 | H2 | `3001` = Participant 1 H2 goals |
| 4000 | ET1 | `4001` = Participant 1 ET1 goals |
| 5000 | ET2 | `5001` = Participant 1 ET2 goals |
| 6000 | PE | `6001` = Participant 1 penalty shootout goals |
| 7000 | ETTotal | `7008` = Participant 2 ETTotal corners |
**Usage:** These encodings are required when validating score data against on-chain Merkle roots, creating trading offers, or settling trades with cryptographic proofs.
### Integrator Notes
* Hydration breaks are represented as `comment` actions with `Data.Text = "Water-drinking break"`. They are not numeric `Stats` keys or a dedicated action type.
* Fouls are not exposed as a separate documented `foul` action in the soccer feed. Use `free_kick` with `Data.FreeKickType != "Offside"` for foul/free-kick handling; offside is `free_kick` with `Data.FreeKickType = "Offside"`.
* Current documented enums include:
* `shot.Data.Outcome`: `OnTarget`, `OffTarget`, `Woodwork`, `Blocked`
* `Data.FreeKickType`: `Safe`, `Attack`, `Danger`, `HighDanger`, `Offside`
* `var.Data.Type`: `Goal`, `Penalty`, `RedCard`, `SecondYellowCard`, `CornerKick`, `MistakenIdentity`, `Other`
* `var_end.Data.Outcome`: `Stands`, `Overturned`
* penalty outcomes: `Scored`, `Missed`, `Retake`
## Documentation
Complete documentation for the TxODDS Soccer data feed
### Version 1.1 Updates
The v1.1 Soccer Feed PDF includes the following integrator-facing updates:
* `Substitution` messages can include `FollowsAction`, linking a confirmed substitution to the originating unconfirmed action.
* `Action Amend` can include `Participant`, identifying the team related to the original action being amended.
* `halftime_finalised` indicates halftime data has been reviewed and verified, and may be sent more than once for the same halftime period.
# Subscription Tiers
Source: https://txline-docs.txodds.com/documentation/subscription-tiers
TxLINE subscription levels and pricing
## Overview
TxLINE offers flexible data access subscriptions, each available with configurable league selections. Subscriptions are priced per 28-day period, and you can choose how many periods you want to subscribe for.
## Subscription Tiers & Pricing
**Conversion Rate**: 1 USD = 1,000 TxL
**What's Included**: All subscriptions include Scores and StablePrice Odds
| ID | Bundle | Delay | Price/28 Days |
| -- | ---------------------------------------------------- | ---------- | ------------- |
| 1 | NFL, MLS, Premier League, World Cup & Int Friendlies | 60 seconds | Free |
| 12 | NFL, MLS, Premier League, World Cup & Int Friendlies | Real-time | Free |
| ID | Bundle | Delay | Price/28 Days |
| -- | ---------------------------------------------------- | --------- | ------------- |
| 1 | NFL, MLS, Premier League, World Cup & Int Friendlies | 0 seconds | Free |
**Subscription Duration**: Subscriptions must be purchased in multiples of 4 weeks (28 days). Minimum term is 4 weeks.
## Confirm
You can verify the current pricing directly from the on-chain program:
```typescript theme={null}
const [pricingMatrixPda] = anchor.web3.PublicKey.findProgramAddressSync(
[Buffer.from("pricing_matrix")],
program.programId
);
const matrix = await program.account.pricingMatrix.fetch(pricingMatrixPda);
matrix.rows.forEach((row) => {
console.log({
serviceLevel: row.rowId,
tokensPerWeek: row.pricePerWeekToken,
samplingInterval: row.samplingIntervalSec,
leagueBundle: row.leagueBundleId,
marketBundle: row.marketBundleId
});
});
```
**Pricing subject to change**: Pricing structure may be updated at any time. Active subscriptions will honor the terms agreed upon at the time of purchase.