> ## Documentation Index
> Fetch the complete documentation index at: https://txline-docs.txodds.com/llms.txt
> Use this file to discover all available pages before exploring further.

# World Cup Free Tier

> Access World Cup and International Friendlies data for free with TxLINE's complimentary tiers

## Start Building with Free World Cup Data

Experience the power of TxLINE's sports data API with our complimentary free tiers. Get access to World Cup and International Friendlies data with no TxL purchase, no credit card, and no commitment. Mainnet offers documented 60-second and real-time options; devnet service levels and sampling intervals follow its current on-chain pricing matrix.

<Note>
  Free means no TxL subscription payment. You still need SOL on the selected Solana network to pay transaction fees and any account rent required by the on-chain `subscribe` transaction. On devnet, request devnet SOL before starting.
</Note>

## What's Included

<CardGroup cols={2}>
  <Card title="Mainnet Free Tiers" icon="trophy">
    **Service Level 1**: World Cup & Int Friendlies with 60-second delay
    **Service Level 12**: World Cup & Int Friendlies in real-time
  </Card>

  <Card title="Historical Replay" icon="clock-rotate-left">
    Full access to historical data for past matches and events analysis.
  </Card>

  <Card title="On-Chain Verification" icon="shield-check">
    Cryptographically verifiable data with Solana blockchain anchoring.
  </Card>

  <Card title="Production Ready" icon="rocket">
    Same reliable infrastructure as our premium tiers with comprehensive documentation.
  </Card>
</CardGroup>

<Info>
  **Perfect For**: Developers building proof-of-concepts, hobbyist projects, learning platforms, or testing TxLINE before a production rollout.
</Info>

## Getting Started

### Step 1: Choose a Network and Set Up Your Wallet

Use the same network for every step: the Solana RPC, TxLINE program ID, guest JWT, and activation endpoint must all match. A devnet subscription transaction cannot be activated on the mainnet API host.

| Network | Free service levels                                | Program ID                                     | API host                        |
| ------- | -------------------------------------------------- | ---------------------------------------------- | ------------------------------- |
| Mainnet | `1` for 60-second delay, `12` for real-time        | `9ExbZjAapQww1vfcisDmrngPinHTEfpjYRWMunJgcKaA` | `https://txline.txodds.com`     |
| Devnet  | `1`; current row reports `samplingIntervalSec = 0` | `6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J` | `https://txline-dev.txodds.com` |

Before you subscribe, confirm that you have:

* A Solana wallet on the selected network.
* Enough SOL on that network for fees and possible rent.
* The matching TxLINE IDL/types for that network.
* The matching `apiOrigin` and `programId` values from the table above.

```bash theme={null}
npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token axios tweetnacl
```

<Info>
  The repository also includes runnable devnet free-tier scripts in [Runnable Devnet Examples](/documentation/examples/devnet-examples). Those examples use the current devnet IDL/types and require Node.js `20+` because of the SSE client dependency in the lockfile.
</Info>

```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" = "devnet";

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<Txoracle>(
  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()}`
  );
}
```

### Step 2: Subscribe to Free Tier

Choose between the free service levels that are enabled on your network. Mainnet offers service level `1` for 60-second delayed World Cup and International Friendlies data and service level `12` for real-time data. The current devnet pricing matrix exposes service level `1` with `samplingIntervalSec = 0`; check the on-chain pricing matrix before relying on any devnet row or interval.

```typescript theme={null}
// Free tier configuration - choose one:
const SERVICE_LEVEL_ID = 1;  // Devnet: samplingIntervalSec = 0; mainnet: 60 seconds
// const SERVICE_LEVEL_ID = 12; // Mainnet real-time World Cup & Int Friendlies
const DURATION_WEEKS = 4; // Subscribe for 4 weeks at a time
const SELECTED_LEAGUES: number[] = []; // Empty for standard bundle

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
);

// Subscribe on-chain
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();

console.log("Subscription transaction:", txSig);
```

<Note>
  **No TxL Payment Required**: Free tiers require no TxL payment. The transaction still registers your wallet subscription on-chain, consumes SOL for normal Solana fees, and must be activated with the matching TxLINE API host.
</Note>

### Step 3: Activate Your API Access

After subscribing on-chain, activate your API token by signing and calling our activation endpoint.

```typescript theme={null}
// Get guest authentication token
const authResponse = await axios.post(`${apiOrigin}/auth/guest/start`);
const jwt = authResponse.data.token;

// Create message to sign
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<Uint8Array> {
  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 your API access
const activationResponse = await axios.post(
  `${apiBaseUrl}/token/activate`,
  {
    txSig,
    walletSignature,
    leagues: SELECTED_LEAGUES,
  },
  {
    headers: { Authorization: `Bearer ${jwt}` }
  }
);

// Save your API token
const apiToken = activationResponse.data.token || activationResponse.data;
console.log("API Token activated successfully!");
```

For the standard free bundle, `SELECTED_LEAGUES = []`, so the exact message signed by your wallet is:

```text theme={null}
${txSig}::${jwt}
```

Use a base64-encoded detached signature, and make sure the signing wallet is the same wallet that submitted the `subscribe` transaction. Do not share your guest JWT or activated API token in public support channels.

### Step 4: Make Your First API Call

You're all set! Start fetching World Cup and International Friendlies data using your activated API credentials.

Check out the complete [API Reference](/api-reference/authentication/start-a-new-guest-session) for available endpoints including:

* **Fixtures** - Get upcoming and current fixture metadata
* **Odds** - Fetch snapshots, historical updates, and stream StablePrice odds
* **Scores** - Fetch snapshots, historical updates, and stream score events
* **Validation Proofs** - Retrieve fixture, odds, and score proofs for on-chain validation

Use [Runnable Devnet Examples](/documentation/examples/devnet-examples) for complete scripts that subscribe to the free tier, activate an API token, connect to streams, and run fixture or score validation simulations.

Data API endpoints use `Authorization: Bearer ${jwt}` for the guest JWT and `X-Api-Token: ${apiToken}` for the activated API token.

<Info>
  If activation or data access fails, use [Troubleshooting](/documentation/examples/troubleshooting) before opening a support ticket. Most activation failures come from a network mismatch, a different signing wallet, or signing the wrong message string.
</Info>

## Ready for More?

Love the free tier? Upgrade to unlock:

<CardGroup cols={3}>
  <Card title="Real-Time Data" icon="bolt">
    Zero delay live data for time-sensitive applications
  </Card>

  <Card title="1000+ Leagues" icon="trophy">
    Access to all major leagues worldwide
  </Card>

  <Card title="Custom Leagues" icon="sliders">
    Choose exactly which leagues you need
  </Card>
</CardGroup>

View our [Subscription Tiers](/documentation/subscription-tiers) to see all available options. Paid tiers start from just **500,000 TxL (\$500) per 28 days**.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need to renew my free subscription?">
    All subscriptions can be purchased for any duration in multiples of 4 weeks (28 days), up to 12 months. Simply re-subscribe when your access expires. There's no cost to renew free tiers.
  </Accordion>

  <Accordion title="Can I upgrade from free tier to paid?">
    Absolutely! You can upgrade at any time by subscribing to a paid tier. Your new subscription will take effect immediately.
  </Accordion>

  <Accordion title="Is there a rate limit on free tier?">
    No rate limits on API calls. Mainnet service level `1` has a 60-second delay, while mainnet service level `12` is real-time. Devnet sampling follows its on-chain pricing matrix; the current level `1` row reports `samplingIntervalSec = 0`.
  </Accordion>

  <Accordion title="Do I need SOL for the free tier?">
    Yes. No TxL purchase is required for the free tier, but the Solana wallet still needs SOL on the selected network to submit the on-chain subscription transaction and cover any account rent.
  </Accordion>

  <Accordion title="What happens if I don't renew?">
    Your API access will expire after the subscription period ends. You can re-subscribe at any time to regain access.
  </Accordion>

  <Accordion title="Can I use this for commercial projects?">
    Yes! The free tier can be used for commercial projects. However, for production applications, we recommend upgrading to real-time data for the best user experience.
  </Accordion>
</AccordionGroup>

***

<Info>
  **Ready to start?** Follow the steps above to subscribe on-chain, activate your API access, and start calling the World Cup data endpoints. No credit card or TxL purchase is required for the free tier.
</Info>