> For the complete documentation index, see [llms.txt](https://docs.molecule.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.molecule.xyz/technical-deep-dive/data/data-api-and-integration.md). # Data API & Integration ### The Data Access Layer The Data Storage and Data Privacy & Access pages describe how research files enter a Lab — how they are encrypted, stored, versioned, and access-controlled. This page describes the other side of the pipeline: how onchain events are indexed into a queryable database, how that data is aggregated with research metadata and editorial content into a unified API layer, and how every consumer in the ecosystem — the frontend, MIRA, external developers, and AI agents — accesses it. Every interaction a user has with Lab data on the Molecule platform — browsing project listings, viewing token prices, reading announcements, querying MIRA, or building an integration against the Labs API — is mediated by the Molecule API. The API is the central data hub that sits between the raw data sources and the consumers that need them. ### Data Sources The Molecule API aggregates data from multiple backends, each responsible for a different category of information. **Amazon Aurora (AWS relational database)** is the primary data store for indexed onchain and application data. Aurora is a cloud-native, fully managed relational database service from AWS. It stores IP-NFT ownership records, IPT contract state, token metadata, treasury balances, crowdsale contributions, Lab creation records, and transaction history — all pre-indexed into relational tables so the API can serve queries without reading directly from the blockchain at request time. **Kamu** provides the research data layer. Every file uploaded to a Lab's data room — its content hash, version history, author DID, access level, encryption metadata, and provenance chain — is tracked in Kamu's provenance database. Kamu also records activity events: file access logs, metadata changes, and the complete append-only version graph for every dataset. The Labs API exposes this data through a GraphQL interface, enabling programmatic read and write access to data rooms. **Sanity CMS** provides editorial and marketing content — project descriptions, team profiles, research category taxonomies, curated homepage content, and blog posts. This content is managed by the Molecule team through Sanity Studio, a customizable content editing interface. Sanity is a third-party headless CMS platform (sanity.io) that stores content on its hosted infrastructure and exposes it through its own API. **GeckoTerminal** provides supplementary token price and market data. The MCP tools that power MIRA's market intelligence pull pricing data from GeckoTerminal in addition to the Molecule API's own indexed market data, providing OHLCV (open, high, low, close, volume) historical price charts and liquidity metrics. ### The Indexing Pipeline Onchain events do not flow directly from the blockchain to the API. There is an indexing layer in between that parses blockchain events and writes them into the Aurora database in a structured, queryable format. When a transaction occurs onchain — IPTs are transferred, a crowdsale receives a contribution, treasury funds are deployed, or any Lab transaction is executed — the blockchain records that event as a transaction receipt with associated logs. Service providers monitor the blockchain, detect relevant contract events from Molecule Protocol contracts, parse the event data (decoding function signatures, extracting parameter values, resolving token metadata), and write the resulting structured records into the Aurora database. This indexing step is what makes the platform performant. Without it, every page load, every search query, and every MIRA conversation would require reading and parsing raw blockchain state — which is slow, expensive, and impractical for a real-time user experience. Instead, the indexer runs continuously in the background, keeping Aurora in sync with the onchain state, and the Molecule API queries Aurora directly. The indexing pipeline handles several data transformations during this process. Raw contract events are decoded into human-readable records. Token metadata (names, symbols, images) is resolved from onchain tokenURI pointers. Pricing data is computed from DEX pool events (swaps, liquidity changes). Ownership graphs are maintained as tokens transfer between wallets. Treasury balances are aggregated across multiple token types. Crowdsale states are tracked through their lifecycle (created, running, settled, failed). The result is a relational database where complex queries — "show me all Labs sorted by treasury size" or "find all IPTs with market cap above $100k" — can be resolved in milliseconds rather than requiring full blockchain scans. ### The API Layer The Molecule API is a GraphQL API that sits on top of the Aurora database and serves aggregated data to all consumers. It is the primary interface through which the platform operates. The API serves two broad categories of data. Market and token data — representing approximately 85% of current API traffic — includes IPT prices, market caps, liquidity depths, holder distributions, trading volumes, IP-NFT metadata, crowdsale states, treasury balances, project listings, and transaction histories. This data originates from onchain events, indexed through the pipeline described above into Aurora. Research and Lab data — representing the remaining 15% — includes data room file listings, file versions, announcements, project activity feeds, and semantic search results. This data is served through the Labs API, which reads from Kamu for file metadata and provenance, and generates presigned S3 URLs through Filebase for file uploads and downloads. The API uses a two-tier authentication model. Read operations (queries) require a consumer credential, issued by the Molecule team upon request. Write operations (mutations) — file uploads, metadata updates, announcements — require both a consumer credential and a service token, which is scoped to a specific wallet address and Lab. Service tokens have configurable expiration and can be extended or revoked through the API. For detailed authentication setup, credential management, and rate limits, see the Labs API reference page. ### How Consumers Access Data Different consumers interact with the data layer through different interfaces, depending on their use case. **The Molecule frontend (Molecule Screener)** consumes the Molecule API's GraphQL endpoints for project listings, token market data, Lab metadata, and activity feeds. It calls the Labs API for data room operations — file uploads, downloads, and encrypted file retrieval. It currently also calls Sanity's API directly for editorial content (project descriptions, blog posts, categories). It performs client-side decryption when users access encrypted files: for new files, it calls `decryptDataKey` to retrieve the unwrapped DEK after the backend re-verifies access conditions against live chain state, and decrypts locally via Web Crypto. **MIRA** accesses data through MCP (Model Context Protocol) tools — structured function calls that the AI model invokes during conversations. MIRA's knowledge base — a curated corpus about Molecule, Molecule's architecture, and the broader ecosystem — is maintained separately and updated through an automated crawl pipeline. **External developers and AI agents** access Lab data through the Labs API, which provides full GraphQL access to data room operations: listing projects, querying files, uploading and versioning research data, creating announcements, and performing semantic search across Labs. For market and token data, they query the Molecule API directly. All these are documented in the References section. ### The Integration Pipeline When a researcher uploads a file to a Lab, the data flows through the full pipeline and becomes available to every consumer in the ecosystem. The file is AES-256-GCM encrypted client-side with a per-file wrapped data encryption key (Onchain-Verified Envelope Encryption), uploaded through the Labs API to Filebase, committed to IPFS and Arweave by Kamu (which records the version, content hash, author DID, and provenance metadata), and referenced onchain in the Lab's Token Bound Account. The onchain reference event is then picked up by the indexer and written to Aurora. At that point, the file is retrievable through the Labs API by any authenticated consumer with the appropriate access level, searchable via the semantic search endpoint, visible in MIRA's project activity responses, and reflected in the Lab's data room size and activity metrics on the frontend. Market data flows through a different path. When a token event occurs onchain — an IPT trade on a DEX, a crowdsale contribution, a treasury deployment — the indexer picks up the event, computes the relevant metrics (new price, updated volume, changed holder count), and writes the results to Aurora. The Molecule API serves the updated data on the next query. MIRA's MCP tools access this data in real time during conversations, supplemented by GeckoTerminal for historical OHLCV charts. Announcements follow the Labs API path. A Lab owner creates an announcement through the Labs API (or the platform UI), optionally attaching data room files. The announcement is stored via Kamu with its timestamp, author, and content, and immediately appears in the project's activity feed, the global activity feed, and MIRA's context when users ask about the project. ### Semantic Search The API exposes a semantic search endpoint that queries across all Labs, files, and announcements in the ecosystem. Queries are processed as natural language — searching for "gene therapy for rare diseases" returns Labs whose data room contents, announcements, and metadata are semantically relevant, not just keyword matches. Search results can be filtered by tags, categories, access levels, and content kinds (files or announcements). Each result includes the matching entity, its parent Lab, and a relevance score. This powers both the platform's search interface and MIRA's ability to discover related projects during conversations. ### Access Levels and Gating The API enforces access levels at the file level, consistent with the access control model described in the Data Privacy & Access page. Public files are accessible to any API consumer without authentication. Admin-restricted files require a valid consumer credential and service token tied to an authorised wallet. Token-holder-gated files are accepted by the API but require onchain verification for decryption — the API serves the encrypted blob and encryption metadata, and only wallets that satisfy the stored access conditions (re-verified against live chain state) can obtain the unwrapped data encryption key (through `decryptDataKey` for current-flow files). This means the API can serve file metadata (path, version, content type, access level) for any file regardless of access level, but the actual file content for encrypted files is only accessible to authorised parties who satisfy the stored access conditions and then decrypt client-side. ### Current Limitations The current API and MCP tool suite is weighted toward market and token data. Several research-oriented capabilities are not yet exposed through the API or MCP tools. These include structured scientific data queries (querying dataset contents by schema or field values), dataset version diffs (comparing what changed between two versions of a file), cross-Lab provenance queries (tracing how a dataset or methodology was shared or derived across multiple Labs), and research file metadata queries for MIRA (the MCP tools currently cannot access data room contents, search across file metadata, or retrieve dataset version histories on behalf of the AI). These gaps mean that MIRA can tell you a project's token price, market cap, and recent announcements, but cannot yet directly inspect the contents of a Lab's data room or compare the scientific substance of two projects' research outputs. Developers building integrations should be aware that the Labs API provides richer data room access than the MCP tools currently expose. The Sanity CMS integration is also in transition. The frontend currently calls Sanity's API directly for editorial content, bypassing the Molecule API. The planned architecture consolidates Sanity content into the Molecule API so the frontend has a single data source. This migration is actively in progress. ### Data Architecture Summary
LayerComponentRole
Data OriginsBlockchain (Eth/Base)Onchain events: transfers, crowdsales, treasury
Researcher uploadsResearch files via Labs API / platform UI
Editorial teamProject content via Sanity Studio
IndexingIndexer / Service ProviderParses blockchain events, writes to Aurora
StorageAmazon Aurora (AWS)Relational DB for indexed onchain + application data
Kamu v2Provenance DB for file versions, DIDs, activity events
IPFS + ArweaveEncrypted research file blobs (ciphertext)
Sanity CMSEditorial content, categories, blog posts
Onchain-Verified Envelope Encryption + AccessResolverWrapped per-file DEKs with conditions stored on Kamu (ODF) and re-verified against live onchain state
APIMolecule API (GraphQL)Aggregates Aurora data → serves market/token/project data
Labs API (GraphQL)Aggregates Kamu data → serves data room operations
MCP ServerExposes 5 tools for AI assistants (market data focused)
ConsumersDeSci Screener (frontend)Platform UI — queries Molecule API + Labs API + Sanity
MIRAAI assistant — queries via MCP tools
External devs / agentsProgrammatic access via Labs API + Molecule API
### Related Pages For the storage pipeline (how research files are stored and versioned): see **Data Storage**. For encryption and access control (how data is protected): see **Data Privacy & Access**. For the GraphQL API reference (data room endpoints, queries, mutations): see **Labs API**. For MIRA's tool capabilities (what the AI can query): see **MCP Tools**.