diff --git a/README.md b/README.md
index 07314ff..a0ea08d 100644
--- a/README.md
+++ b/README.md
@@ -95,12 +95,15 @@ Use one network consistently. Devnet subscribe transactions must use the devnet
 
 ## Current Examples
 
-The current copy-paste examples live in the hosted documentation pages rather than a top-level `examples/` directory:
+The hosted documentation pages provide the guided integration flows. Runnable end-to-end scripts are available in [`examples/devnet/scripts`](https://github.com/txodds/tx-on-chain/tree/main/examples/devnet/scripts) and [`examples/mainnet/scripts`](https://github.com/txodds/tx-on-chain/tree/main/examples/mainnet/scripts):
 
 - [Quickstart](https://txline.txodds.com/documentation/quickstart) - purchase, subscribe, activate, and API-token header setup.
 - [Fetching Snapshots](https://txline.txodds.com/documentation/examples/fetching-snapshots) - fixtures, odds, and scores snapshots.
 - [Streaming Data](https://txline.txodds.com/documentation/examples/streaming-data) - odds and scores Server-Sent Events.
 - [On-Chain Validation](https://txline.txodds.com/documentation/examples/onchain-validation) - validation proof retrieval and program calls.
+- [`purchase_tokens_usdt.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/purchase_tokens_usdt.ts) - Devnet TxLINE token purchase using a backend quote and fake Devnet USDT.
+- [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) - V2 and V4 score-validation comparison, including the state-changing V4 validation flow.
+- [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) - custom-league subscription and paid V4 odds validation on devnet.
 
 The `backup/` directory is a historical archive of older Anchor examples and IDL snapshots. It is kept for reference only and should not be treated as the current integration path.
 
diff --git a/documentation/examples/devnet-examples.mdx b/documentation/examples/devnet-examples.mdx
index 9fd40cf..330150e 100644
--- a/documentation/examples/devnet-examples.mdx
+++ b/documentation/examples/devnet-examples.mdx
@@ -35,12 +35,15 @@ yarn ts-node examples/devnet/scripts/subscription_free_tier.ts
 
 | Script | What it demonstrates |
 |--------|----------------------|
+| [`purchase_tokens_usdt.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/purchase_tokens_usdt.ts) | Purchasing TxLINE tokens on devnet with a backend quote and fake Devnet USDT, with local transaction-safety verification before signing. |
 | [`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. |
+| [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) | V2 and V4 score-validation comparison, including V4 multiproof payloads, validation-credit purchase, and a state-changing `validateStatV4` transaction. |
+| [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) | Custom-league subscription, odds discovery, and paid V4 odds validation with validation credits and `validateOddsV4`. |
 | [`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. |
 
@@ -83,6 +86,19 @@ const payload = {
 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.
 </Warning>
 
+## V4 Validation
+
+V4 is a paid, state-changing validation path. The API returns a validation `payload` and signature; the examples serialize the payload with the matching IDL/types, add an Ed25519 verification instruction, purchase validation credits, and submit the V4 transaction.
+
+| Data | API request | On-chain instruction | Runnable devnet example |
+|------|-------------|----------------------|-------------------------|
+| Scores | `/scores/stat-validation-v4?fixtureId=...&seq=...&statKeys=...` | `validateStatV4` | [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) |
+| Odds | `/odds/validation-v4?messageId=...&ts=...` | `validateOddsV4` | [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) |
+
+<Warning>
+Unlike the V2 examples, the V4 examples submit transactions and purchase validation credits. Run them with a devnet wallet and the matching devnet IDL/types; do not substitute a mainnet wallet or endpoint.
+</Warning>
+
 ## 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.
diff --git a/documentation/examples/onchain-validation.mdx b/documentation/examples/onchain-validation.mdx
index 3a3e189..8f13451 100644
--- a/documentation/examples/onchain-validation.mdx
+++ b/documentation/examples/onchain-validation.mdx
@@ -17,14 +17,15 @@ description: "Validate scores data using cryptographic Merkle proofs"
 
 ## 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.
+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, V2 multi-stat, and V4 state-changing validations.
 
-The public `/api/scores/stat-validation` endpoint supports both validation shapes:
+The score-validation endpoints support the following validation paths:
 
 | 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. |
+| `statKeys=1,2,...` at `/api/scores/stat-validation-v4` | `validateStatV4` | Paid, state-changing score validation with a signed multiproof payload. |
 
 Use the same network for the API request, IDL/types, program ID, and on-chain root PDA.
 
@@ -389,6 +390,21 @@ For complete runnable versions, use:
 | [`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. |
 
+## V4 Validation
+
+V4 validates an API-provided payload and signature in a state-changing transaction. The response contains a `payload` and `signature`; serialize the payload with the selected network's matching IDL/types, hash the serialized bytes with SHA-256, and add the corresponding Ed25519 verification instruction before the V4 call.
+
+Before sending the transaction, purchase validation credits with `purchaseValidationCredits`. The V4 instructions require the signing user, the user's validation-state PDA, the instructions sysvar, and the matching daily Merkle-roots PDA.
+
+| Data | Proof endpoint | On-chain instruction | Runnable devnet example |
+|------|----------------|----------------------|-------------------------|
+| Scores | `/api/scores/stat-validation-v4?fixtureId=...&seq=...&statKeys=...` | `validateStatV4(payload, strategy)` | [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) |
+| Odds | `/api/odds/validation-v4?messageId=...&ts=...` | `validateOddsV4(payload)` | [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) |
+
+<Warning>
+V4 is not a drop-in replacement for the V2 `.view()` examples: it purchases validation credits and submits a transaction. Start with the runnable devnet scripts, use the devnet endpoint, program ID, and generated types together, and review the transaction before signing.
+</Warning>
+
 ## Common Validation Errors
 
 | Symptom | What to check |