โ๏ธAPI Access (Beta)
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 Discord community 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:
files
File[]
Yes
Array of files to include in the proof of invention
Example Request:
curl -X POST \
https://molecule.xyz/api/v1/inventions \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: multipart/form-data' \
-F '[email protected]' \
-F '[email protected]'
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
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:
Use the
transaction
object from the API responseSubmit a transaction to any supported EVM blockchain (listed in
supportedEvmChainIds
)Use the
payload
as transaction data andrecipient
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
API Rate Limits: During the beta period, the API is limited to 100 requests per day per API key.
File Storage: Files are processed to create the merkle tree but are not stored on our servers.
Transaction Handling: The API returns the transaction data, but you are responsible for submitting the transaction to the blockchain.
Getting Support
If you encounter any issues or have questions about the API, please join our Discord community for 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
Last updated