jup-ag · 0xanmol · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026
diff --git a/.claude/rules/decisions.md b/.claude/rules/decisions.md
@@ -268,3 +268,44 @@ Track all redirects added to `vercel.json` here for visibility:
 - Reorganise sidebar: Swap (overview), Meta-Aggregator (order-and-execute + API refs), Router (build + submit + API refs), Advanced, Routing Integration, Guides, Migration
 **Rationale:** Two clear paths reduce decision fatigue. Absorbing fees and routing eliminates page-hopping for core concepts. Profile-targeted migration pages let developers find their specific upgrade path without reading irrelevant content.
 **Migration notes:** Redirects added for `swap/fees` → `swap/order-and-execute`, `swap/routing` → `swap`, `swap/build/other-instructions` → `swap/build/common-instructions`.
+
+### [2026-07-09] Document transaction submission against tx.jup.ag (Solana JSON-RPC)
+**Status:** implemented
+**Scope:** content | api-reference
+**Files affected:** `transaction/submit.mdx`, `api-reference/transaction/submit.mdx`, `openapi-spec/transaction/transaction.yaml`, `changelog/index.mdx`, `swap/index.mdx`, `portal/rate-limits.mdx`
+**Source:** `jup-ag/beam` (Beam v2), Slack thread with Kyle/Groovie/Sayantan
+
+**Context:** Beam v2 exposes a direct Solana JSON-RPC endpoint at `https://tx.jup.ag` that implements `sendTransaction`. The team wants to promote it as the primary transaction landing path over the REST `POST api.jup.ag/tx/v1/submit`, which no external integrators currently use. The REST endpoint still works.
+**Decision:**
+- `transaction/submit.mdx` leads with `tx.jup.ag`: point any Solana client (`@solana/web3.js` `Connection` or `@solana/kit`) at it, authenticate with the `x-api-key` header, call `sendTransaction`
+- Document it as send-only (only `send*` methods) so integrators keep their own RPC for blockhash and confirmation
+- Keep the tip requirement and the 16 tip receiver accounts unchanged (verified in the beam source)
+- Reshape the OpenAPI spec from a REST body to the JSON-RPC envelope; keep the legacy REST endpoint mentioned in a `<Note>` rather than deleting it
+- Endpoint auth verified by live probe: no `x-api-key` = keyless (allowed), invalid key = `401`
+**Rationale:** A one-line endpoint change (set RPC URL to `tx.jup.ag`) is the lowest-friction integration story and matches how the product is now built. Keeping the legacy REST endpoint documented as a `<Note>` avoids breaking the (unused but live) path while steering new integrations to the RPC endpoint.
+**Resolved (Kyle / groovie, 2026-07-09):**
+- Methods: advertise ONLY `sendTransaction`. `sendJitoBundle` is internal-teams-only; `sendAndConfirmTransaction` is scheduled for deprecation. Docs updated.
+- Auth: `tx.jup.ag` will require an API key (not keyless). Keyless advertising removed from the docs; `security` in the OpenAPI made required.
+- Rate limits: a single limit across all tiers (anti-abuse only, generous), API key required. Exact number not set yet, so the docs describe the model without a number. The tiered 20/50/100 bucket in `quota.toml` is for the api.jup.ag REST paths only.
+- Analytics/logs: confirmed the dev platform will surface transaction-landing analytics/logs (Beam telemetry → ClickHouse). Docs follow-up on `portal/analytics` + `portal/logs` deferred until the submit-page UI ships.
+
+**Still open:**
+1. Whether the `Swap` API-key permission covers the `tx.jup.ag` host. `portal/api-keys.mdx` line left unchanged pending confirmation.
+2. Credits/metering on `tx.jup.ag` (docs say zero credit cost; unverified since it bypasses the gateway's credit metering).
+3. `tx.jup.ag`'s exact rate-limit number.
+4. Deprecation timeline for the REST `POST /tx/v1/submit`.
+5. Publishing timing: Kyle wants to advertise `sendTransaction` now; groovie wants to hold until internal-team migration and all integrations work. PR should not merge until aligned.
+6. Follow-up: update the `/build` code examples in `swap/build/index.mdx` and the mention in `swap/quote-and-swap.mdx` once `tx.jup.ag` is confirmed GA.
+7. Jito tips + priority-fee guidance (groovie, check in later): `swqosOnly` is not shipped yet, so it has been removed from the docs. A future section should advise how and when to use jito tips and priority fees, including that beam adds a jito tip when `swqosOnly` is false and none is set.
+
+### [2026-07-10] Move transaction submission out of Swap into a "Transaction Landing" section
+**Status:** implemented
+**Scope:** navigation
+**Files affected:** `docs.json`
+**Linear issue:** DEV-328 (seeds YY's broader "transactions and landing" section)
+
+**Context:** `/transaction/submit` documents `tx.jup.ag`, a product-neutral landing endpoint that accepts any signed transaction, not just swaps. It was nested under Docs > Swap > Router as a discovery convenience (see [2026-04-07]), but it isn't swap-specific. YY raised making it a dedicated section and anmol agreed it should live outside Swap.
+**Decision:** Add a new Docs-tab `menu` item "Transaction Landing" (sibling to Swap, Lend, etc.) and move `transaction/submit` + `api-reference/transaction/submit` into it, out of the Swap "Router" group. Supersedes the [2026-04-07] "keep in the Swap sidebar for now" placement.
+**Rationale:** Landing is cross-cutting (any transaction, not just swaps). A dedicated section is the home for DEV-328's planned content (transaction types, landing optimisation, Beam, glossary); this seeds it with the submit page for YY to expand.
+**Alternatives considered:** Keep under Swap/Router (rejected: not swap-specific). A new top-level tab (rejected: products are `menu` items under the Docs tab, not tabs).
+**Migration notes:** Nav-only. URLs unchanged (`/transaction/submit`, `/api-reference/transaction/submit`), so no redirects needed and cross-links are unaffected.
diff --git a/.claude/rules/product-learning.md b/.claude/rules/product-learning.md
@@ -387,6 +387,14 @@ Jupiter Forecast is a new in-house primitive: native Solana binary prediction ma
 - [2026-04-07] Jupiter operates one of the highest-staked validators on Solana. `/submit` opens this landing pipeline to integrators. Key selling points: validator stake, MEV protection (no intermediaries), sub-second landing, zero credit cost.
 - [2026-04-07] Recommended integration pattern: run `/submit` in parallel with existing RPC submission for zero-risk comparison. Whichever lands first wins.
 - [2026-04-16] `/submit` costs zero API credits on all plans (free, Developer, Launch, Pro) and works with keyless access. The only cost is the SOL tip in the transaction.
+- [2026-07-09] Transaction submission is now primarily a Solana JSON-RPC endpoint at `https://tx.jup.ag` (Beam v2), not the REST `POST api.jup.ag/tx/v1/submit` (which still works). Integrators point any Solana client at `sendTransaction` and authenticate with the `x-api-key` header. Per Kyle (2026-07-09) an API key WILL be required, but it is NOT enforced yet: confirmed with real funds on 2026-07-09 that a valid signed swap sent keyless (no `x-api-key`) landed and finalized on mainnet, same as the keyed send. An invalid key returns `401`, but no key at all is currently accepted. Docs advertise API-key-required as forward guidance (the safer claim), so publishing should be coordinated with actual enforcement, or the docs will be ahead of live behaviour. It is send-only (only the `send*` methods; `getHealth` etc. return "Method not found"), so integrators keep their own RPC for blockhash and confirmation. The public path enforces a Jupiter tip (min 0.001 SOL) to one of the same 16 tip receiver accounts. Verified with a live SOL→USDC swap through `tx.jup.ag` (via `/build`) and both `@solana/web3.js` and `@solana/kit` send paths.
+- [2026-07-09] The dedicated submit rate-limit bucket (Keyless 20 / Free 50 / Paid 100 RPS) is defined in `developer-platform` `api-gateway/auth-service/config/quota.toml`, keyed by the REST paths `/tx/v1/submit` and `/swap/v2/submit` (200/500/1000 per 10s window). The api-gateway (host `api.jup.ag`) rewrites those paths to `tx.juprpc.com/submit`. `tx.jup.ag` is a separate direct-to-beam load balancer, absent from that repo, so it does NOT inherit this bucket.
+- [2026-07-09] Per Kyle: `tx.jup.ag` will require an API key and apply a single rate limit across all tiers (anti-abuse only, generous since revenue scales with landed transactions). Exact number not set yet. Differs from the tiered REST buckets above; docs describe the model without a number until it is set.
+- [2026-07-09] Publishing is unresolved: Kyle wants to start advertising `sendTransaction`; groovie wants to hold until internal-team migration and all integrations are working. The docs PR should not merge until they align.
+- [2026-07-09] Verified live (external key) against the beam api-v2 design spec (TX-105): `skipPreflight` must be `true` (explicit `false` → `-1015 "skipPreflight must be true"`), `maxRetries` must be `0` (non-zero → `-1015 "maxRetries must be 0"`), both default correctly if omitted. External error codes: `-1013` insufficient tip, `-1014` missing tip, `-1015` invalid param, `-1016` bad encoding.
+- [2026-07-10] CORRECTION (groovie, beam dev): `swqosOnly` is NOT shipped yet. I wrongly documented it from the design spec plus a live test where `swqosOnly:true` "landed". That test was invalid: JSON-RPC servers silently ignore unknown config fields, so an unimplemented param yields the same "accepted + landed" result as a real one. Landing only proves the tx was valid, not that the param took effect (its routing effect is not observable from a confirmation check). Lesson: for an accept-path param, "it landed" is NOT verification; only reject-path params (skipPreflight/maxRetries, which returned specific `-1015` messages) were genuinely verified. Never document a param unless its effect is observed. Future (groovie, check in later): the section should advise how/when to use jito tips + priority fees, and note that if `swqosOnly` is false with no jito tip set, beam adds one.
+- [2026-07-09] `tx.jup.ag` methods are role-gated: **only `sendTransaction` is available to external integrators.** `sendJitoBundle`, `sendAndConfirmTransaction`, and `sendYoloModeTransaction` all require `RoleTag::Internal` and error with `-1012` for external callers (groovie confirmed the beam-side `require_role(&role, &[RoleTag::Internal], "sendJitoBundle")` check). `sendAndConfirmTransaction` is also scheduled for deprecation. Caveat on my own probing: a malformed-params probe of `sendJitoBundle` returned `-32602` (params are deserialized before the role check runs), which looked reachable but is not. So: integrator docs cover `sendTransaction` alone.
+- [2026-07-09] Confirmed by Sayantan: the developer platform will show transaction-landing analytics/logs (fed by the Beam telemetry → ClickHouse ingestion, `beam_transaction_sent_v1`). Docs follow-up for `portal/analytics` + `portal/logs` is deferred until the submit-page UI ships. Nothing to document yet.
 
 ---
 

diff --git a/.claude/rules/style-guide.md b/.claude/rules/style-guide.md
@@ -31,7 +31,7 @@ Technical but approachable. Professional and precise, not cold or overly formal.
 | `/order`          | order endpoint, order API              | Always backtick the path in prose              |
 | `/build`          | build endpoint, build API              | Always backtick the path in prose              |
 | `/execute`        | execute endpoint, execute API          | Always backtick the path in prose              |
-| `/submit`          | submit endpoint, submit API            | Always backtick. API at `api.jup.ag/tx/v1/submit`, not under `/swap/v2/` |
+| `/submit`          | submit endpoint, submit API            | Always backtick. Primary endpoint is the `tx.jup.ag` Solana JSON-RPC endpoint (`sendTransaction`); the legacy REST `api.jup.ag/tx/v1/submit` still works. Docs page at `/transaction/submit` |
 | Meta-Aggregator    | meta aggregator, MetaAggregator        | The `/order` + `/execute` integration path. Capitalised, hyphenated. |
 | Router             | Metis Router (in most contexts)        | The `/build` + `/submit` integration path. Say "Router" in prose, mention Metis only when explaining what the Router uses under the hood. |
 
@@ -208,3 +208,4 @@ Format: `- [YYYY-MM-DD] Decision: rationale`
 - [2026-04-16] British English spelling for docs prose (e.g. "randomise", "optimise", "colour"). Do not Americanise existing British spellings.
 - [2026-06-17] Write in plain engineer English. Before showing any page, scan the prose for (1) em dashes, (2) the AI-slop phrases in the Words to Avoid table ("ship", "blast radius", "before it ever counts against your plan", "at a glance", rhetorical triplets). Prefer the concrete action and the literal effect over flourish. "An API key used in a client the user controls is not private" beats "When you ship a key, that key is no longer a secret".
 - [2026-06-21] Fee settlement / rev-share docs use abstract placeholders for the integrator/Jupiter split (`y%` integrator, `x%` Jupiter, `y = 100 − x`; `F bps` for the total), never concrete bps or split ratios (no "85/15", no "100 bps" example). Splits are negotiated per-integrator and Jupiter aims to maximise its share, so a concrete example would anchor integrators to a number that may be lower than what is actually charged. Keep the split illustration general (e.g. `y/100 × F`).
+- [2026-07-09] Transaction submission is documented against the `tx.jup.ag` Solana JSON-RPC endpoint (`sendTransaction`), not the REST `POST api.jup.ag/tx/v1/submit` (which still works, treated as legacy). Code examples point a Solana client (`Connection` for web3.js, `createSolanaRpcFromTransport` for kit) at `https://tx.jup.ag` with the API key in the `x-api-key` header, and note it is send-only (keep your own RPC for blockhash and confirmation). Supersedes the [2026-04-07] REST-URL guidance below.
diff --git a/api-reference/transaction/submit.mdx b/api-reference/transaction/submit.mdx
@@ -1,6 +1,6 @@
 ---
-openapi: /openapi-spec/transaction/transaction.yaml post /submit
-title: "Submit Transaction"
-description: "Submit a signed transaction through Jupiter's landing infrastructure"
-llmsDescription: "POST /submit endpoint for Jupiter Transaction API at api.jup.ag/tx/v1/submit. Submits any valid signed Solana transaction through Jupiter's transaction landing infrastructure. Requires a SOL tip of at least 0.001 SOL (1,000,000 lamports) to one of the 16 tip receiver accounts. Request body: signedTransaction (base64-encoded signed transaction). Response: signature (transaction signature). Works with /build swap transactions, non-Jupiter transactions, or any other signed transaction. Requires x-api-key header."
+openapi: /openapi-spec/transaction/transaction.yaml post /
+title: "Send Transaction"
+description: "Land a signed transaction through Jupiter's infrastructure with the tx.jup.ag Solana JSON-RPC endpoint"
+llmsDescription: "sendTransaction JSON-RPC method for the Jupiter Transaction API at https://tx.jup.ag. Lands any valid signed Solana transaction through Jupiter's transaction landing infrastructure. tx.jup.ag implements the standard Solana sendTransaction method (encoding base64), so any Solana client can point at it. Requires a SOL tip of at least 0.001 SOL (1,000,000 lamports) to one of the 16 tip receiver accounts. Request body: JSON-RPC 2.0 envelope with method sendTransaction and params [base64-signed-transaction, config]. Response: JSON-RPC result is the transaction signature. Requires the x-api-key header. Send-only: keep your own RPC for blockhash and confirmation."
 ---
diff --git a/changelog/index.mdx b/changelog/index.mdx
@@ -19,6 +19,26 @@ llmsDescription: "Changelog for Jupiter developer APIs, SDKs, and docs. Tracks b
 
 ---
 
+<Update label="July 2026" description="">
+
+## Transaction Submission: tx.jup.ag JSON-RPC endpoint
+
+Land signed transactions through Jupiter's infrastructure by pointing any Solana client at `https://tx.jup.ag`. It implements the standard Solana `sendTransaction` JSON-RPC method, so adoption is a one-line endpoint change: set your RPC URL to `tx.jup.ag` and pass your Jupiter API key in the `x-api-key` header.
+
+* Same landing infrastructure as before (Jupiter Beam, SWQoS, DoubleZero), now reachable as a drop-in RPC endpoint
+* Requires a minimum tip of 0.001 SOL to one of the 16 tip receiver accounts
+* Send-only: keep your own RPC for blockhash and confirmation
+* Requires a Jupiter API key
+
+The legacy REST endpoint `POST https://api.jup.ag/tx/v1/submit` continues to work.
+
+- [Transaction Submission Docs](/transaction/submit)
+- [API Reference](/api-reference/transaction/submit)
+
+</Update>
+
+---
+
 <Update label="June 2026" description="">
 
 ## Swap API: JupiterZ Integrator Fees