[docs-agent] Add Solana Trader API docs (REST spec, overview, nav) - #1620
Open
alchemy-bot wants to merge 4 commits into
Open
alchemy-bot wants to merge 4 commits into
alchemy-bot wants to merge 4 commits into
Conversation
Adds a new Solana Trader API surface under Chains > Solana with three operations: * GET /order — swap quote plus optional assembled base64 transaction when a taker is supplied. * GET /build — raw swap instructions for composing into your own transaction. * POST /quote-multiple-output-mints — quote a single input mint against up to 32 candidate output mints in one call. Spec: src/openapi/solana-trader/solana-trader.yaml, OpenAPI 3.1 modeled on src/openapi/prices/prices.yaml. Server https://solana-mainnet.g.alchemy.com/v2 with {apiKey} in the path (docs-demo default). Introduces x-compute-units and x-rate-limit-cus on each operation (100 placeholders), the first REST spec in this repo to carry those extensions. Overview: content/api-reference/solana/solana-trader-api-overview.mdx patterned after solana-jito-bundles-overview.mdx (not the historical Photon nft-api location). Nav slot in content/docs.yml placed between Solana Photon API and Solana Jito Bundles and Transactions, with flattened: true so method pages nest under the overview. Also adds a # Solana: Trader API block in content/api-reference/pricing-resources/pricing/compute-unit-costs.mdx between the Photon and Jito blocks (100 CU / 100 throughput placeholders), and a Related APIs entry on content/api-reference/solana/solana-api-overview.mdx. Refs DOCS-227
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 800e942e5e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Comment on lines
+39
to
+41
| | [GET /order](/docs/chains/solana/solana-trader-api/solana-trader-api/get-swap-order) | Get a swap quote. Include a `taker` to also receive an unsigned base64 transaction; omit `taker` for quote fields only. | 100 | 100 | | ||
| | [GET /build](/docs/chains/solana/solana-trader-api/solana-trader-api/build-swap-instructions) | Return raw swap instructions for composing into your own transaction. | 100 | 100 | | ||
| | [POST /quote-multiple-output-mints](/docs/chains/solana/solana-trader-api/solana-trader-api/quote-multiple-output-mints) | Quote a single input mint against up to 32 candidate output mints in one call. | 100 | 100 | |
There was a problem hiding this comment.
Update all three links to match the routes generated by the current content indexer. Because each operation's first tag is Solana Trader API Endpoints, buildOperationPath inserts solana-trader-api-endpoints between the API slug and operation ID; without an include-tags configuration that removes the tag, the listed /solana-trader-api/<operation> targets are not indexed and will return 404, while the generated pages live under /solana-trader-api/solana-trader-api-endpoints/<operation>.
Useful? React with 👍 / 👎.
Vlad flagged that the sidebar was rendering as Solana Trader API > Solana Trader API Endpoints > <op>, one level deeper than Solana Photon API. The extra middle level was the OpenAPI operation tag ('Solana Trader API Endpoints'): Fern groups OpenAPI operations by tag under the api entry even with flattened: true, whereas Solana Photon's OpenRPC methods carry no tags and render flat.
Fix matches the Portfolio spec pattern (src/openapi/portfolio/portfolio.yaml uses no tags on its operations and renders flat under a single api heading in docs.yml). Drops tags from /order, /build, and /quote-multiple-output-mints so all three operations render directly under the Solana Trader API section.
Refs DOCS-227
Comprehensive rewrite of src/openapi/solana-trader/solana-trader.yaml against Vlad's spec-review pass.
/order:
* swapMode enum extended with ExactOut. otherAmountThreshold documented as max input on ExactOut, min output on ExactIn.
* Response fields promoted to required (always present): mode, otherAmountThreshold, priceImpact, priceImpactPct, inUsdValue, outUsdValue, swapUsdValue, swapType, gasless, router, routePlan, transaction, taker, signatureFeeLamports, prioritizationFeeLamports, rentFeeLamports, signatureFeePayer, prioritizationFeePayer, rentFeePayer. transaction/taker/fee-payer fields nullable via type: [string, null].
* lastValidBlockHeight kept optional (omitted, not null, when there is no usable transaction).
* Router-side requestId dropped (not emitted by this service; out of scope with /execute per Metis's README).
* errorCode 3 dropped (never emitted, no gasless path). errorCode 1 and 2 retained. Added error field alongside errorCode/errorMessage for 200 rejections.
* routePlan[] steps gained bps (0-10000) and optional usdValue. percent typed as integer 0-100.
* Error responses (400, 401, 429) removed per Vlad's ask (200 only for now).
* Three named examples: quoteOnly, withTransaction, pricedButUnexecutable.
/build:
* Request params overhauled. Dropped receiver and swapMode (silently ignored by Metis). slippageBps clarified: Metis default 50 when omitted, string rtse accepted alongside 0-10000 integer.
* Added payer, dexes (mutually exclusive with excludeDexes), platformFeeBps (0-10000 with feeAccount required when positive), feeAccount, maxAccounts (1-64), wrapAndUnwrapSol, destinationTokenAccount / nativeDestinationAccount (mutually exclusive), blockhashSlotsToExpiry (1-300, with 256-300 as 501 note), tipAmount (> 0), computeUnitPricePercentile (medium | high | veryHigh only), mode (fast only), forJitoBundle.
* Response schema rewritten. Dropped addressLookupTableAddresses, computeUnitLimit, prioritizationFeeLamports, requestId.
* Added quote fields (inputMint, outputMint, inAmount, outAmount, otherAmountThreshold, swapMode ExactIn-only, slippageBps, priceImpactPct, routePlan), computeBudgetInstructions, otherInstructions, tipInstruction, addressesByLookupTableAddress (map keyed by lookup-table address, null when no tables in use), blockhashWithMetadata with a snake_case fetchedAt object (secs_since_epoch, nanos_since_epoch) and 32-byte integer array blockhash.
* setupInstructions kept required (always present, may be empty).
* Errors documented: 400 with plain {error: string} body, 501 for numeric computeUnitPricePercentile and blockhashSlotsToExpiry 256-300, 502 for Metis / priority-fee / lookup-table / blockhash / tip-instruction upstream failures. 401 and 429 omitted (gateway-only).
* Single realistic 200 example.
/quote-multiple-output-mints:
* Response envelope rewritten. quotes changed from array to object keyed by output mint (in request order), each value only { inAmount, outAmount }. Shared contextSlot at the top level (omitted when no quote carried one). requestId removed.
* Request body: dropped slippageBps (silently ignored server-side). Kept inputMint, outputMints (1-32 unique pubkeys, none equal to inputMint), amount (JSON string; number returns 400), swapMode (ExactIn or ExactOut, ExactOut = desired output per mint independently).
* 400 documented with common causes (over 32 mints, amount as number, duplicate mint, mint equal to input).
* Introduced dedicated MultiQuoteEntry component instead of reusing OrderResponse.
Shared:
* ErrorResponse simplified to { error: string } only.
* Amount parameter description updated for ExactOut semantics.
* redocly source lint clean (2 baseline warnings: info-license and operation-4xx-response on /order, both intentional).
Refs DOCS-227
…put-mints Matches Vlad's earlier ask for /order — all three operations now document 200 only. Removes 400 + 501 + 502 from /build and 400 from /quote-multiple-output-mints. Also drops the now-unreferenced ErrorResponse component from the source (bundler would strip it via --remove-unused-components anyway, but keeping the source tidy). Refs DOCS-227
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Solana Trader API documentation surface under Chains → Solana. The spec is REST (OpenAPI 3.1, first REST spec in this repo to carry
x-compute-units/x-rate-limit-cus), not JSON-RPC, and is modeled onsrc/openapi/prices/prices.yaml. Nav sits between Solana Photon and Solana Jito.Three public operations:
GET /order— swap quote; include atakerto also receive an unsigned base64 transaction, omittakerfor a quote-only response (transaction: null).GET /build— raw Solana swap instructions for composing into a larger transaction of your own.POST /quote-multiple-output-mints— quote a single input mint against up to 32 candidate output mints in one call.Alchemy routes Trader API requests through Metis only. No JupiterZ / Dflow / OKX references (per the intake).
Files
src/openapi/solana-trader/solana-trader.yamlhttps://solana-mainnet.g.alchemy.com/v2with{apiKey}path param (docs-demodefault). CU metadata viax-compute-units: 100+x-rate-limit-cus: 100on every op.content/api-reference/solana/solana-trader-api-overview.mdxtitle/description/subtitle),## Background,## Endpoint,## Methodstable with the same 4-column layout Photon uses (Method / Function / CU cost / Throughput CUs),## Related. Method-page links use the flattened/docs/chains/solana/solana-trader-api/solana-trader-api/<op>shape.content/docs.yml- section: Solana Trader APIblock inserted between Solana Photon API and Solana Jito Bundles and Transactions, with- api: Solana Trader API; api-name: solana-trader; flattened: true. No slug pin needed (kebab-case of the title matches the nav slug).content/api-reference/pricing-resources/pricing/compute-unit-costs.mdx# Solana: Trader APIsection between the Photon and Jito blocks with a{/* cu:auto product="solana-trader" */}table.content/api-reference/solana/solana-api-overview.mdxSolana Trader APIto the## Related APIslist.Auto-generation:
scripts/generate-open-api.shpicks up the newsrc/openapi/solana-trader/directory and bundles tocontent/api-specs/alchemy/rest/solana-trader.json, whichscripts/generate-metadata.tsthen exposes atdev-docs.alchemy.com/metadata.json. No manual registration needed.Linear
DOCS-227 — https://linear.app/alchemyapi/issue/DOCS-227/add-solana-trader-api-docs-rest-spec-overview-mdx-nav-wiring
Verification
pnpm run generate:rest— bundledsolana-trader.jsonsuccessfully. Only baselineno-unused-componentswarnings on the dereferenced JSON, matching the existing pattern for prices/nft/notify.pnpm run validate:rest— spec validates. Sourcesolana-trader.yamlproduces 1 warning (info-license) matching the repo baseline (prices.yaml has the same).pnpm run validate:docs-yml— passes.pnpm exec eslintandnpx prettier --checkon all touched files — clean.Unresolved / placeholders (need vlad to finalize before we mark the service GA)
Per the intake's "if a fact is missing, list the gap in the PR" rule, these values are ones we agreed to ship as placeholders now and revisit before the public launch:
https://solana-mainnet.g.alchemy.com/v2per vlad's placeholder guidance; the actual public routing prefix may end up namespaced (/trader/...) once the service is deployed at the gateway. Probes from outside currently return401 Must be authenticated!(gateway default for unknown prefixes), so no external verification was possible.100 / 100placeholders on all three operations. Source of truth istopconfig.ymlinOMGWINNING/chain-config, which docs-agent cannot read.OrderResponseandBuildResponsemirror Jupiter's Swap V2/orderand/buildschemas (the intake's designated contract reference). If Alchemy's actual response envelope diverges from Jupiter's shape (extra wrapping, renamed fields, etc.), those descriptions will need a follow-up. TheerrorCode1/2/3 semantics also come from Jupiter — confirm they carry over on Alchemy's side./quote-multiple-output-mintscap is32(updated live in-thread from the initial8hint).Screenshot / preview note
The overview table follows the Photon
Method | Function | CU cost | Throughput CUsshape verbatim. Method-name links point at/docs/chains/solana/solana-trader-api/solana-trader-api/<op-slug>(doubled section slug, same pattern as Photon and Jito underflattened: true), so once the Vercel preview builds, all three method pages should nest under the overview cleanly.