๐Ÿ”ฌ
Molecule Docs
  • Introduction
    • ๐Ÿ”ฌWhat is Molecule?
    • ๐Ÿ’กWhy Molecule?
  • Proof of Invention (PoI)
    • ๐Ÿ’กIntro to Proof of Invention (PoI)
    • ๐Ÿ’ฎHow to register inventions?
    • โš™๏ธAPI Access (Beta)
  • MOLECULE LABS
    • ๐ŸงชIntro to Molecule Labs
    • ๐Ÿง‘โ€๐Ÿ”ฌSubmit a Project
    • ๐Ÿ“How is data stored?
  • IP-NFTs
    • โšกIntro to IP-NFT
    • ๐Ÿ›๏ธIP-NFT legal structure
    • โ“Why mint an IP-NFT?
    • โœจHow to mint an IP-NFT?
    • ๐Ÿ› ๏ธTechnical Components of IP-NFTs
      • โš™๏ธTechnical Details for Developers
      • ๐Ÿ“ญSmart Contract Addresses
  • ๐Ÿง‘โ€๐Ÿ”ฌIP Tokens
    • ๐Ÿ’ŠWhat are IP Tokens?
    • โœจHow to tokenize IPTs from an IP-NFT?
    • โš–๏ธWhat are risks of IP-NFTs and IPTs?
    • ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆWhat is a crowdsale of IPTs?
    • โœจHow to participate in a crowdsale of IPTs?
  • IP Tokenization Guide
    • ๐Ÿ—บ๏ธIP Tokenization Guide
    • ๐ŸฆWallets
Powered by GitBook
On this page
  • Overview
  • Authentication
  • API Endpoints
  • Error Handling
  • Next Steps After API Response
  • File Requirements
  • Usage Guidelines
  • Getting Support
  • Beta Program
  1. Proof of Invention (PoI)

API Access (Beta)

PreviousHow to register inventions?NextIntro to Molecule Labs

Last updated 14 days ago

Overview

The PoI API allows developers to programmatically generate cryptographic proofs for their invention files. This API is currently in beta and requires an API key for access.

Important: This API is currently in beta. To request API access, please join our and reach out to our team to obtain an API key.

Authentication

All API requests require authentication using an API key. Use the Bearer token authentication method:

Authorization: Bearer YOUR_API_KEY

API Endpoints

Generate Proof of Invention

Creates a merkle tree from uploaded files and returns the merkle root along with transaction data.

Endpoint: POST /api/v1/inventions

Content-Type: multipart/form-data

Request Parameters:

Parameter
Type
Required
Description

files

File[]

Yes

Array of files to include in the proof of invention

Example Request:

curl -X POST \
  https://poi.molecule.xyz/api/v1/inventions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@document1.pdf' \
  -F 'files=@document2.pdf'

Success Response:

{
  "success": true,
  "data": {
    "proof": {
      "format": "simple-v1",
      "tree": [
        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba"
      ],
      "values": [
        {
          "value": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
          "treeIndex": 1
        },
        {
          "value": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
          "treeIndex": 2
        }
      ]
    },
    "transaction": {
      "data": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "to": "0x1DEA29b04a59000b877979339a457d5aBE315b52"
    }
  },
  "metadata": {
    "supportedEvmChainIds": [1, 8453],
    "apiVersion": "1.0",
    "timestamp": "2025-05-22T15:30:45.123Z"
  }
}

Error Handling

The API returns appropriate HTTP status codes along with error messages in the response body:

Error Response Format

{
  "success": false,
  "error": {
    "message": "Error message describing what went wrong",
    "code": 400
  },
  "metadata": {
    "supportedEvmChainIds": [1, 8453],
    "apiVersion": "1.0",
    "timestamp": "2025-05-22T15:31:12.456Z"
  }
}

Common Error Codes

Status Code
Description

400

Bad Request - Invalid input parameters

401

Unauthorized - Invalid or missing API token

415

Unsupported Media Type - Invalid Content-Type header

500

Internal Server Error - Something went wrong on the server

Next Steps After API Response

After receiving a successful response from the API, you'll need to submit the transaction to the blockchain to store your proof on-chain:

  1. Use the transaction object from the API response

  2. Submit a transaction to any supported EVM blockchain (listed in supportedEvmChainIds)

  3. Use the payload as transaction data and recipient as the recipient address

Example (using viem)

const tx = await walletClient.sendTransaction({
  data: result.transaction.data,  // Merkle root from API response
  to: result.transaction.to,  // Contract address from API response
  from: yourWalletAddress,
  ...
})

// Wait for transaction confirmation
const receipt = await waitForTransactionReceipt(walletClient, { hash: tx })

This transaction creates a permanent, timestamped record of your proof of invention on the blockchain.

File Requirements

  • Maximum file size: 100MB (total for all files)

  • Supported file types: All file types are supported

Usage Guidelines

  1. API Rate Limits: During the beta period, the API is limited to 100 requests per day per API key.

  2. File Storage: Files are processed to create the merkle tree but are not stored on our servers.

  3. Transaction Handling: The API returns the transaction data, but you are responsible for submitting the transaction to the blockchain.

Getting Support

Beta Program

As part of our beta program, we're actively seeking feedback to improve the API. If you have suggestions or feature requests, please share them with us on Discord.


Last updated: May 22, 2025

If you encounter any issues or have questions about the API, please join our for support.

โš™๏ธ
Discord community
Discord community