Sample audits · Earlier documentation audits

Magic Eden developer documentation, May 2026

Magic Eden API Documentation — Independent Review. Published in full as delivered; only internal notes and delivery correspondence were removed.

AuditedMagic Eden developer documentation
Date29 May 2026
How it ranearlier documentation audit; severities are as rated in that report and were not re-rated
Re-check, 11 October 202621 could not check
9
Critical or High as first rated
7
Medium as first rated
5
Low as first rated
0
Informational as first rated

Severities as published in our original report; these findings were not re-reviewed by hand the way the sample audits were. The 11 October 2026 re-check status is shown under each finding where it maps.

Prepared for: Magic Eden, Developer Documentation team Date of review: 2026-05-29 (revised; original 2026-05-28) Documents reviewed: docs.magiceden.io documentation corpus mirrored 2026-05-28 — 142 files (~1977 KB) covering /docs/, /reference/, /recipes/, /changelog/ Review type: Documentation quality, correctness, and developer-integration-readiness assessment across the SOL V2 / EVM V4 / BTC Ordinals product surfaces

Executive summary

The Magic Eden API documentation set is structurally complete (142 of 142 enumerated URLs returned 200) and serves its primary purpose: documenting the published REST API surface across three product surfaces (Solana marketplace V2, EVM marketplace V4, Bitcoin Ordinals & Runes) alongside integration recipes and a brief changelog. The corpus carries 21 findings across the documentation quality dimensions reviewed.

Documentation is usable for integration but the issues catalogued below introduce avoidable friction for developers, with one finding (F-1) representing a category of issue that materially misleads integrators reading the affected pages.

Top-priority items requiring attention:

SeverityCountHighest-impact finding
Critical1F-1: Two legacy-URL variants contain silently stale parameter sets missing priority-fee parameters present in the canonical pages
High8F-2 through F-9 (cross-surface taxonomy + security scheme + param naming + server URL + recipe code + paging-metadata documentation + wallet docs hosted off-domain)
Medium7F-10 through F-16 (legacy URL duplicates; recipe line-number drift; broken changelog links; rate-limit defaults; deprecation markers; missing overview pages; orphan host)
Low5F-17 through F-21 (renderer-specific markup; meta-tag dev-subdomain leak; typo; undated changelog; uneven recipe coverage)

The CRITICAL item (F-1) is the most acute developer-experience issue: a developer reading the affected legacy-URL pages to integrate /v2/instructions/buy or /v2/instructions/sell-now writes request shapes WITHOUT the priority-fee parameters their integration needs, resulting in transactions submitted with default fees (likely lower than current chain conditions warrant) until they discover the canonical page. Remediation is mechanical (align the two pages OR mark legacy URLs as deprecated with redirect) and removes the largest source of silent integration regression.

The HIGH-severity items concentrate on a single theme: cross-surface consistency. The three product surfaces (SOL V2, EVM V4, BTC Ordinals) have independently-evolved OpenAPI titles, version numbers, security scheme declarations, server URL conventions, and parameter vocabularies. A developer integrating across multiple surfaces writes 3 parallel auth-handling code paths, 3 parallel URL-resolver helpers, and accepts inconsistent parameter naming (tokenAccount vs tokenATA). Each surface in isolation is coherent; the union is not. Consolidating per-surface conventions toward a unified policy would materially reduce per-developer integration overhead.

Methodology

The review was a systematic read-through of every file in the documentation mirror, applying a documentation-quality checklist tuned for vendor-published REST API surfaces with extensions for Magic Eden's specific multi-product-surface architecture. The checklist covered:

Each finding was severity-graded against developer-impact criteria:

Findings IDs are opaque sequence numbers (F-1 through F-21) with no semantic content outside this report.

Substrate verification was mechanical: file counts, parameter-name walks, security-scheme declarations, server-URL declarations, and -1 URL-slug content comparisons were performed via grep / diff / awk over the local mirror and are independently reproducible.

Findings

Critical

F-1 — Two legacy -1 URL variants contain silently stale parameter sets

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Documentation content integrity — silent content divergence on retained legacy URLs Affected files.

Observation. Both URL pairs return HTTP 200 at the live docs site and present what appear to be sibling versions of the same endpoint documentation. However, the -1 variants document a STRICTLY SMALLER parameter set than their canonical (non--1) counterparts:

The 40 other -1 URL variants in the documentation are byte-identical to their canonical counterparts (acceptable duplicate-on-rename behavior); only these 2 carry silently divergent content.

Developer impact. A developer landing on the -1 URL — most likely via search-engine indexing of the older URL slug or a stale third-party link — constructs API requests WITHOUT priority-fee parameters. The resulting transactions are submitted with default fees, which on a congested Solana network can mean substantially slower confirmation or outright drop. The developer experiences this as intermittent integration failure with no obvious cause; the documentation they're reading appears complete because both surface 200-OK responses with full-looking specifications.

Recommendation. Either (a) align the two -1 pages with their canonical counterparts (preferred — eliminates the content divergence at the source), or (b) emit a 301 redirect from the -1 URL to the canonical URL (closes the divergence at the request layer; documents the rename intent). Option (b) is mechanically simpler and applies platform-wide to the 42 -1 pages confirmed as legacy artifacts.

High severity

F-2 — 15 legacy -1 URL slugs exist with no canonical counterpart

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. URL-slug naming convention coherence Affected files. 15 reference pages with -1 suffix and no non--1 sibling, including: getcollection-1, getcollectionstats-1, gettokens-1, and the entire get_v2-ord-btc-runes-*-1 + post_v2-ord-btc-runes-{order,psbt-order}-{create,cancel}-1 family (12 BTC Ordinals pages).

Observation. The -1 suffix convention reasonably implies "version 1 of the URL slug retained after a rename" — yet for these 15 pages, the -1 is the ONLY URL slug that exists. A developer reading docs.magiceden.io/reference/getcollection-1 will reasonably assume there is (or was) a getcollection counterpart and may search for it. There is none.

Developer impact. Cognitive overhead during integration: developer wastes time searching for canonical counterparts that don't exist; integrator-facing tooling (link checkers, doc-completeness reports) flags these as missing-pair-of-renamed-URLs when in fact they're the original-and-only URL.

Recommendation. Rename the 15 orphan -1 slugs to canonical names without the suffix, OR document explicitly (in a per-surface overview page) that the -1 suffix is preserved for some endpoints as a stable identifier and does not imply duplicate or rename history.

F-3 — Three OpenAPI titles and three incoherent version numbers across product surfaces

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. API taxonomy + version-numbering coherence Affected files. All 128 endpoint-spec files (133 reference total minus 5 overview/auth pages).

Observation. Three distinct OpenAPI specifications, distinguishable by their root-level info.title and info.version:

The version numbers do not form a coherent versioning scheme: the largest surface by file count (SOL V2) has the lowest version + a non-standard OAS-suffix; the EVM surface has the highest version. A developer reading the docs cannot derive which "API" their endpoint belongs to from the version-number convention.

Developer impact. Consumer codebase typing (e.g., TypeScript client generation from each spec) emits inconsistent package names + version markers. Cross-surface code reviews lose the ability to reason about which API surface a change affects from version-number context alone.

Recommendation. Consolidate to a per-surface convention with the product surface in the title (e.g., Magic Eden — Solana V2 API, Magic Eden — Bitcoin Ordinals API, Magic Eden — EVM V4 API) and either align version numbering (all start fresh at 1.0.0 per surface, or apply a unified version policy) or explicitly document the per-surface taxonomy in an overview doc cross-referenced from every endpoint page.

F-4 — Security scheme inconsistency across product surfaces

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. API security metadata + OpenAPI spec consistency Affected files. All 128 endpoint-spec files.

Observation. Three different declarations for what is presented as a unified "Bearer Authorization" pattern:

At runtime, all three surfaces accept identical Authorization: Bearer <api_key> headers; the divergence is only at the OpenAPI specification layer. But:

Developer impact. A typed-client generator producing TypeScript from each spec emits inconsistent type names (BearerAuth vs bearerAuth) AND inconsistent auth-handling code paths (HTTP-class scheme vs apiKey-class scheme). A developer integrating across all 3 surfaces writes 3 separate auth-handling code paths even though the runtime auth header is identical. BTC integrators have no spec-level signal that auth is required or what scheme to use, and must discover this out-of-band (from the Solana or EVM API key pages, or by trial-and-error against the live endpoints).

Recommendation. Standardize on one scheme name + type across all three surfaces. Add explicit securitySchemes declaration to all BTC Ordinals API files. Apply "security": block at operation level for all BTC endpoints that require auth.

F-5 — Parameter naming inconsistency for the same concept across sibling endpoints

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. API parameter vocabulary consistency Affected files. Sell + buy endpoint family.

Observation. Three SOL "sell" endpoints use tokenAccount as the query parameter for the seller's associated token account: get_instructions-sell, get_instructions-sell-cancel, get_instructions-sell-change-price. The fourth, get_instructions-sell-now, uses tokenATA for the same concept. The same divergence appears on the buy side: get_instructions-buy-now uses tokenATA.

Both tokenAccount and tokenATA refer to the Associated Token Account (ATA) — same underlying Solana concept, two different parameter names within the same API surface.

Developer impact. A developer integrating both buy-flow and buy-now-flow (or sell + sell-now) writes different query strings — ?tokenAccount=... vs ?tokenATA=... — for the same input. Easy to get wrong; not obvious from naming convention which surface uses which.

Recommendation. Pick one naming convention (tokenAccount is more conventional outside the Solana ecosystem; tokenATA is Solana-idiomatic and shorter) and migrate the other endpoint family to match. Backward-compatibility option: accept both for a deprecation window and document the migration.

F-6 — Server URL form inconsistency across product surfaces; one orphan host

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. API endpoint canonicity + URL configuration Affected files. All 128 endpoint-spec files plus getcollectionstats-1.

Observation. Three different servers[].url conventions across the surfaces:

Additionally, one file (getcollectionstats-1) declares a root-level server URL (https://api-mainnet.magiceden.dev) but the specific /collection_stats/search/bitcoin path declares an INNER servers override pointing to a UNIQUE host: https://stats-mainnet.magiceden.dev. This is the only endpoint using the stats-mainnet host AND the only endpoint using path-level servers override.

Developer impact. A consumer using a single base-URL configuration in their HTTP client cannot derive any one server URL form from another — they must maintain a per-surface URL-resolver helper. Worse, the orphan stats-mainnet host is silently buried in a path-level override; a developer using a typed client may not parse path-level servers overrides at all and submit requests to the wrong host (200-OK on the wrong host returns wrong data; 404 on the wrong host returns nothing).

Recommendation. Standardize server URL form across all three surfaces — likely "host + version-and-product-surface path in server URL" matching the EVM convention. Either fold the stats-mainnet endpoint under the main host or document the orphan host in a per-surface overview page.

F-7 — Recipe code unconditionally accesses an optional vendor-response field

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Recipe code-sample correctness Affected files. recipes/sol-list-an-nft (line 60), recipes/sol-bid-on-an-individual-nft (line 58), and likely recipes/sol-place-collection-bid-from-escrow (similar pattern).

Observation. The Transaction response schema documented in get_instructions-sell (and reused across SOL V2 instructions endpoints) declares two properties: tx (referencing IBuffer) marked "required": ["tx"], and txSigned (also referencing IBuffer) NOT in the required list. Per the spec, the API may return only tx; txSigned is optional.

Three recipes access txData.txSigned.data unconditionally:

const serializedTxData = new Uint8Array(txData.txSigned.data);
const tx = VersionedTransaction.deserialize(serializedTxData);

If the API returns only the required tx field (consistent with its own schema declaration), the recipe throws TypeError: Cannot read property 'data' of undefined. The recipe code path is documented as the primary integration pattern.

Developer impact. Developer copies recipe code into integration → integration works in the developer's testing because the API happens to return txSigned → ships → production traffic hits a code path where the API returns only tx → uncaught TypeError, transaction never built, user-facing error. Latent bug propagated by recipe.

Recommendation. Either (a) align the spec with the recipe by promoting txSigned to required (if the API always returns it), or (b) align the recipe with the spec by adding a presence guard and fall-back to tx:

const buffer = txData.txSigned?.data ?? txData.tx.data;
const serializedTxData = new Uint8Array(buffer);

F-8 — Paging-metadata header documented on only 2 of 25 paged endpoints

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. API capability documentation completeness Affected files. 25 endpoint-spec files declare offset + limit query parameters (paging surface); only get_collections and its -1 duplicate document the ME-Pub-API-Metadata request header and corresponding response header for retrieving paging metadata (total / start / end indices).

Observation. The ME-Pub-API-Metadata header pattern, when set on a request, returns total / start / end paging metadata that allows clients to compute "is there a next page" without making a redundant probe call. This is documented at get_collections with full OpenAPI markup: request-header parameter declaration + response-header schema. None of the other 23 paged endpoints (get_collections-symbol-listings, get_wallets-wallet-address-tokens, get_mmm-pools, etc.) document this header at all.

Developer impact. Two readings are possible: (a) the header is supported on all 25 paged endpoints but documented on only one (the developer never knows the capability exists; pages the API by probing-for-empty-page-after-N-pages), or (b) the header is supported only on get_collections and the documentation correctly reflects the restriction (the developer assumes consistency and writes code that handles the header on all 25 endpoints, which silently fails on 23). Either reading is a documentation gap.

Recommendation. Document the metadata header on every paged endpoint where it works (add parameter + response-header declaration to each of the 23 missing endpoints), OR document the per-endpoint restriction explicitly (e.g., a per-endpoint "Paging metadata header supported: yes / no" note in each paged endpoint's narrative section).

F-9 — Wallet API documentation hosted at a separate docs domain, outside the main documentation surface

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Documentation discoverability across product domains Affected files. docs/wallet-docs.md (4 lines total) is a redirect-only stub pointing to https://docs-wallet.magiceden.io/. The actual Wallet API documentation lives at the sibling host and is NOT included in docs.magiceden.io/llms.txt enumeration.

Observation. The main docs entry-point (docs.magiceden.io) advertises a "Wallet Docs" navigation entry that resolves to a 4-line stub redirecting readers to a different docs domain. A developer integrating Magic Eden's Wallet API via the marketplace docs entry-point cannot discover the actual Wallet docs without following the redirect, AND the redirect-target URL is NOT a sub-path under docs.magiceden.io/* — it's a sibling host requiring a separate discovery + indexing pass.

Developer impact. LLM-driven integration tools that consume docs.magiceden.io/llms.txt (the agent-readable documentation index) have ZERO context for Wallet API integration — the stub redirect is listed but its target content is not indexed. Human developers landing on docs.magiceden.io and searching for "wallet API authentication" find a 4-line page that tells them the docs are elsewhere; click-through cost + index-fragmentation overhead per Wallet-API-integration question.

Cross-vendor framing note (V2, 2026-05-29). This multi-host documentation pattern is not unique to Magic Eden. Subsequent independent reviews of other vendor documentation sites have observed analogous host-fragmentation cases (most notably a host-migration history at a peer vendor where adjacent product docs ended up at sibling hosts after platform consolidation). The pattern is now substrate-grounded across multiple vendor instances, suggesting cross-host documentation enumeration is a generalizable concern for integrators rather than a Magic-Eden-specific quirk. The recommendation below remains the same; the cross-vendor framing notes that integrator tooling targeting llms.txt-class enumeration may benefit from supporting multi-host documentation indexes broadly, which would aid not only Magic Eden integrators but also integrators of any vendor with adjacent product docs at sibling hosts.

Recommendation. Either fold wallet docs under docs.magiceden.io/wallet/* paths (single documentation domain — preferred for discoverability), OR explicitly cross-link the wallet host from each top-level overview page + ensure docs.magiceden.io/llms.txt includes references to the wallet domain's content (multi-host indexed documentation pattern).

Medium severity

F-10 — 40 of 57 legacy -1 URL variants are byte-identical duplicates of their canonical counterparts

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. URL-slug lifecycle hygiene (ReadMe.io platform behavior) Affected files. 40 -1 URL variants where diff <canonical>.md <variant>-1.md returns zero output.

Observation. ReadMe.io retains old URL slugs as duplicates after content rename. 40 of Magic Eden's 57 -1 variants are byte-for-byte identical to their canonical counterparts. Both URLs are live at the docs site (200-OK on both). The duplication is a platform behavior; the count is a vendor authoring choice (not cleaning up after content moves).

Developer impact. Search-engine SEO duplicate-content penalty; LLM agent indexers see the same OpenAPI spec twice, doubling token cost during ingestion; developer reading "two pages" for a single endpoint wastes attention validating they're identical.

Recommendation. Emit 301 redirects from -1 URLs to canonical URLs (preserves backwards-compatibility for indexed external links + signals canonicity to search engines), OR delete the -1 slugs entirely if no external links point to them.

F-11 — Recipe code-annotation line numbers drift from actual code-block reality

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Recipe documentation maintenance discipline Affected files. All 6 recipes.

Observation. Each recipe ends with a documentation pattern that lists code-block sections with line-range annotations: e.g., # import @solana/web3.js followed by <!-- javascript@4-8 -->. The line ranges are intended to point readers at the relevant lines of the code block above. In every recipe checked, the annotations are systematically off: in recipes/sol-list-an-nft, the imports section claims <!-- javascript@4-8 --> but the actual import block is at lines 7-11; the RPC connection section claims line 14 but is at line 17; the send + confirm section claims lines 59-64 but is at lines 62-67. The drift is consistent with the code block having grown by 3 lines (likely a JSDoc comment block added) after the annotations were authored, with the annotations not updated.

Developer impact. Developers using the line-range annotations to navigate the code blocks are pointed at slightly wrong lines, finding adjacent-but-different content; mild trust erosion.

Recommendation. Re-derive line-range annotations from current code-block contents; ideally automate this at documentation build time so future code-block edits don't drift the annotations.

F-12 — Broken cross-references in changelog

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Internal link integrity Affected files. changelog/sorting-and-filtering-enhancements links to /reference/solana-overview (no such file — only solana-api-keys exists); changelog/mmm links to /reference/mmm-pool-pricing (no such file — the math content is embedded in reference/mmm).

Observation. Two of approximately 14 unique cross-references from the changelog files to /reference/* URLs resolve to 404. Substrate verification: every cross-referenced filename was probed against the local mirror; 2 of 14 had no corresponding .md file.

Developer impact. Reader following changelog links lands on 404 pages; mild trust erosion, plus the missing target content (presumably a Solana API overview, presumably a dedicated pool-pricing page) is documentation the reader expected to find.

Recommendation. Either create the missing pages, or fix the link targets to the actual existing page (e.g., /reference/solana-api-keys for the overview link; /reference/mmm#pool-pricing anchor for the pricing link).

F-13 — Rate-limit default policies differ between Solana and EVM surfaces without documented rationale

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Cross-surface policy consistency Affected files. reference/solana-api-keys and reference/evm-api-keys.

Observation. Solana API keys page: "This public API is free to use, and the default limit is 120 QPM or 2 QPS." EVM API keys page: "This public API is free to use, and the default limit is 180 QPM." Two different defaults (120 vs 180 QPM); one states a QPS supplement, the other is silent on QPS; both use the same Airtable application form for higher tiers. BTC Ordinals surface declares no rate-limit policy at all (no btc-api-keys page exists — see F-15).

Developer impact. Developer building cross-surface tooling assumes uniform vendor rate-limit policy and budgets calls at the lower default (120 QPM); finds out at integration time that EVM allows 50% more. Conversely, developer who reads only the EVM page assumes 180 QPM is the company default and hits the 120 QPM ceiling on the Solana surface unexpectedly.

Recommendation. Align defaults across surfaces (likely 120 QPM is the conservative choice; if EVM truly supports 180, document the per-surface rationale + supplement Solana to match). Add a BTC-specific rate-limit page (see F-15 for the broader missing-overview issue).

F-14 — Deprecated-field markers carry no replacement-pointer description

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Schema deprecation hygiene Affected files. Eight files in the *-activities* family (4 endpoints × 2 with their -1 duplicates): get_collections-symbol-activities, get_tokens-token-mint-activities, get_wallets-owner-activities, get_wallets-wallet-address-activities.

Observation. Each of the 8 files declares a collection property in the activity response schema marked "deprecated": true. None of the 8 declarations carries a description field naming the replacement (e.g., "description": "Deprecated; use collectionSymbol instead"). Developers using typed-client generators (which surface OpenAPI deprecation as deprecation warnings) receive the warning without guidance on what to migrate to.

Developer impact. Deprecation warning triggers a migration task in the developer's project planning; developer has to read 8 schema files and the surrounding endpoint docs to figure out what the replacement is.

Recommendation. Add OpenAPI description field to each "deprecated": true marker naming the replacement field. If multiple endpoints share the same migration, document once in a referenced location.

F-15 — Per-surface overview pages missing for Solana and BTC

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Documentation completeness — per-surface overview pages Affected files. evm-api-overview.md exists (12 lines, brief but present). No solana-api-overview.md exists; only solana-api-keys.md (auth-only). No btc-api-overview.md AND no btc-api-keys.md exists.

Observation. Of the three product surfaces, only EVM has a dedicated overview page documenting clusters / chains / general usage. Solana developers must read the API-keys page (which is auth + rate-limit focused) for cluster + endpoint orientation; BTC Ordinals developers have neither overview nor api-keys page and must reverse-engineer the surface from the 27 endpoint reference files alone.

Developer impact. New-developer onboarding friction is uneven across surfaces. SOL and BTC integrators take longer to reach "first successful call" than EVM integrators despite SOL being the largest surface by file count.

Recommendation. Author solana-api-overview.md and btc-api-overview.md (and a btc-api-keys.md) matching the existing evm-api-overview structure. Cross-link from each endpoint reference page's narrative section.

F-16 — Path-level server URL override creates an orphan host pattern

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. OpenAPI spec authoring + endpoint canonicity Affected files. getcollectionstats-1 only.

Observation. The file declares a root-level servers: [{url: "https://api-mainnet.magiceden.dev"}] AND a path-level override servers: [{url: "https://stats-mainnet.magiceden.dev"}] inside /paths/<path>/. This file is:

Developer impact. A consumer using a typed client that parses only root-level servers (a common simplification) silently hits the wrong host for this endpoint. The pattern's high overhead (special-case host) and low frequency (one endpoint) make it easy to miss in client-implementation review.

Recommendation. Fold the endpoint under the main host (move the stats-mainnet content to api-mainnet), OR if the stats host is intentional, document the orphan host in a per-surface overview page + add a narrative banner to the endpoint's reference page explaining the override.

Low severity

F-17 — Renderer-specific JSX wrapper in one reference page

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Renderer portability Affected files. reference/mmm.md (359 lines).

Observation. Content is wrapped in <HTMLBlock>{...}</HTMLBlock> containing HTML and MathML markup for pool-pricing mathematics. This is the only file in the mirror using <HTMLBlock>. Renders correctly only at the readme.io-hosted Magic Eden docs site; appears as raw JSX in any plain-markdown reader.

Developer impact. Developers reading the docs offline (via mirror, via LLM ingestion, via plain-markdown reader) see uninterpreted JSX wrappers. Math content is not readable in those contexts.

Recommendation. If platform-portable rendering is a goal, rewrite math sections using a portable markup (LaTeX or KaTeX-compatible) supported by more markdown renderers. Alternative: render JSX out at build time for offline-readable mirrors.

F-18 — Documentation platform's development subdomain leaked in HTML meta tags

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Documentation site hygiene Affected files. All pages (HTML head; not present in mirrored .md content).

Observation. The HTML <head> of every page at docs.magiceden.io includes <meta name="readme-subdomain" content="tallal-test"> and <meta name="readme-repo" content="tallal-test-20d452ba6b96">. The slug "tallal-test" suggests the documentation site was originally bootstrapped under a developer's personal test subdomain in the docs platform and never renamed to a production-grade slug.

Developer impact. No effect on API correctness. Light reputational signal that the docs site internal configuration was not cleaned up after launch.

Recommendation. Rename the docs platform project to a production-grade slug (e.g., magic-eden-docs or magiceden-api).

F-19 — Typo in EVM API overview

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Copy-edit Affected files. reference/evm-api-overview line 3.

Observation. "The Magic Eden EVM APIs are designed to empower developers in creating innovative experiences to gather data for for Ethereum and its L2 chains." Double "for".

Recommendation. Remove the duplicate "for".

F-20 — Changelog entries carry no dates or publish timestamps

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Changelog hygiene Affected files. Both changelog/mmm and changelog/sorting-and-filtering-enhancements.

Observation. Both files use present-tense announcement language ("We are excited to announce…", "We're excited to announce…") with no date / version / publish timestamp anywhere in the file. A reader cannot tell whether the announcement is from 6 months ago or 3 years ago; cannot correlate the AMM Pool API introduction with the current MMM endpoint set; cannot determine deprecation timing.

Recommendation. Add a publish-date header to each changelog entry (ISO 8601 date is sufficient). Consider also version-tagging each entry (e.g., "Released in v2.x" cross-referenced with the API version numbers per F-3).

F-21 — Recipe coverage uneven across product surfaces

Could not check Re-check of the published text, 11 October 2026: the documentation site now blocks automated access.

Category. Recipe documentation completeness Affected files. All 6 recipes.

Observation. Recipe distribution: 3 SOL (sol-list-an-nft, sol-bid-on-an-individual-nft, sol-place-collection-bid-from-escrow), 3 BTC (btc-create-and-submit-runes-listing-order, btc-swap-runes, btc-sweep-runes), 0 EVM. The 3 BTC recipes are exclusively Runes-focused — no Ordinals-NFT recipe, no rare-sats recipe. The 3 SOL recipes cover only bid + list + escrow-bid — no buy-now, no cancel, no MMM pool flows. The EVM surface has 17 endpoint references and zero recipes.

Developer impact. New integrators looking for "how do I X on chain Y" find answers only for a sparse intersection. EVM integrators have no end-to-end recipe at all.

Recommendation. Backfill recipes for each major endpoint family per surface (buy-now on SOL; Ordinals-NFT listing on BTC; basic data + write flows on EVM). Even minimal "happy path" examples close the discoverability gap substantially.

Conclusion

Magic Eden's three-surface API documentation is functionally complete (every endpoint is documented with at least an OpenAPI specification + path key + parameter set) and the mirror integrity is excellent (zero fetch failures, zero HTML residue). The 21 findings catalogued above are documentation-quality issues, not API-design issues — the underlying APIs work; the documentation around them has accumulated rough edges that introduce avoidable friction for developers integrating across the SOL / EVM / BTC surfaces.

The single CRITICAL item (F-1) is mechanically addressable: align two legacy URL variants with their canonical counterparts, OR emit a 301 redirect. The HIGH-severity items concentrate on cross-surface consistency — three product surfaces have independently-evolved conventions for security schemes, version numbers, server URL forms, and parameter vocabularies. Consolidating per-surface conventions toward a unified policy would materially reduce per-developer integration overhead and would likely simplify Magic Eden's own internal documentation maintenance burden by reducing the per-surface authoring divergence over time.

The remaining MEDIUM and LOW items are individual improvements that compound over a developer's integration experience: a missing replacement-pointer on a deprecated field, an undated changelog, a typo in an overview. None is blocking; each is cheap to fix; cumulatively they signal documentation-team capacity and care.

We hope this review is useful. Happy to clarify any specific finding, discuss prioritization, or revisit specific surface areas in more depth.

Independent documentation review prepared by Ondřej Dvořák / Pukapasoft. © 2026 Pukapasoft. Findings IDs are opaque sequence numbers internal to this report.