NFT Endpoints
FabricBloc NFT Microservice - User Guide
Welcome to the FabricBloc NFT Service! This guide explains how to use the NFT collection, minting, metadata, contract deployment, and health features provided by this service. It is intended for end users, integrators, and developers interacting with the NFT API.
Note: Only ERC-721 contract type and Ethereum testnet are supported for now. Public minting, royalties, and advanced gRPC features are not yet implemented.
Overview
FabricBloc NFT Microservice provides RESTful APIs for managing NFT collections, minting and burning NFTs, handling metadata, and deploying smart contracts. The service is built with Go, uses PostgreSQL, and is designed for extensibility and clean architecture.
HTTP Port: 8094 (REST API endpoints)
gRPC Port: 9094 (Internal microservice communication, placeholder)
Database Port: 5433 (PostgreSQL)
Base URL
<http://api.dev.fabricbloc.com/v1/nft>Swagger/OpenAPI Docs
<https://api.dev.fabricbloc.com/v1/nft/swagger/index.html>Returns a paginated list of NFT collections belonging to the authenticated user only.
Number of items per page (default 10)
Page number (default 1)
Paginated list of collections.\n- items: List of collections (name, symbol, description, status, timestamps, mint_settings, user_id, owner_address, network, contract_type)\n- total: Total number of collections\n- page: Current page\n- limit: Items per page\n- has_next: True if there is a next page\n- has_previous: True if there is a previous page
Invalid query parameters
Unauthorized (missing or invalid token)
Internal server error
GET /v1/nft/collections HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"has_next": true,
"has_previous": true,
"items": [
{
"chain_id": "text",
"contract_address": "text",
"contract_type": "text",
"created_at": "text",
"description": "text",
"id": "text",
"mint_settings": {
"current_supply": 1,
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"owner_address": "text",
"status": "text",
"symbol": "text",
"updated_at": "text",
"user_id": "text"
}
],
"limit": 1,
"page": 1,
"total": 1
}This endpoint allows an authorized user to create a new NFT collection.
This is an authorized API; a valid JWT token is required.
Users can create multiple collections using this endpoint.
The collection data is stored in the database.
Currently, only ERC-721 contract type and ethereum testnet configurations are supported. (pass sepolia)
The API expects collection details such as name, symbol, network, storage method, and owner address.
Returns the created collection object on success.
Mint price applies to all NFTs on public mint only. The mint price is in wei. Calculate the wei value for network selected. 1 ETH = 10¹⁸ wei (1000000000000000000 wei) Calculator reference: https://eth-converter.com/
Note:
Do not use public mint as its not implemented yet. use mint_settings.is_public_mint to false or keep it empty
Metadata fields are optional and only stored in the database, for now this metadata is not used while deploying the contract.
Royalty percentage is not implemented yet. use mint_settings.royalty_percentage to 0 or keep it empty
Royalty recipient is not implemented yet. use mint_settings.royalty_recipient to 0 or keep it empty
Max Supply Rules:
ERC721: Collection-level max supply. Set max_supply to 0 for unlimited supply, or any positive number for limited supply.
ERC1155: Collection-level max supply (same as ERC721). Per-token max supply is set during individual token minting.
Example: {"id":"b3e1c2d4-1234-5678-9abc-def012345678","name":"My NFT Collection","symbol":"MYNFT","network":"ethereum","contract_type":"ERC-721","storage_method":"ipfs","user_id":"00000000-0000-0000-0000-000000000001","owner_address":"0x1234567890abcdef1234567890abcdef12345678","status":"draft","metadata":{},"mint_settings":{},"created_at":"2024-06-01T12:00:00Z","updated_at":"2024-06-01T12:00:00Z"}
Example: {"error":"Invalid request parameters"}
Example: {"error":"Internal server error"}
POST /v1/nft/collections HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 452
{
"contract_type": "text",
"description": "text",
"metadata": {
"base_token_uri": "text",
"custom_attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"external_url": "text",
"image_uri_pattern": "text",
"meta_description": "text",
"name_pattern": "text"
},
"mint_settings": {
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"owner_address": "text",
"storage_method": "text",
"symbol": "text"
}{
"chain_id": "text",
"contractAddress": "text",
"contractType": "text",
"createdAt": "text",
"deletedAt": "text",
"description": "text",
"id": "text",
"metadata": {
"base_token_uri": "text",
"custom_attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"external_url": "text",
"image_uri_pattern": "text",
"meta_description": "text",
"name_pattern": "text"
},
"mintSettings": {
"current_supply": 1,
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"ownerAddress": "text",
"status": "text",
"storageMethod": "text",
"symbol": "text",
"transactionHash": "text",
"updatedAt": "text",
"userID": "text"
}Returns a single NFT collection by ID, only if it belongs to the authenticated user.
Collection ID (uuid)
Collection details (same fields as list)
Invalid ID format
Unauthorized (missing or invalid token)
Collection not found or access denied
Internal server error
GET /v1/nft/collections/{id} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"chain_id": "text",
"contract_address": "text",
"contract_type": "text",
"created_at": "text",
"description": "text",
"id": "text",
"mint_settings": {
"current_supply": 1,
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"owner_address": "text",
"status": "text",
"symbol": "text",
"updated_at": "text",
"user_id": "text"
}Partially updates a single NFT collection by ID, only if it belongs to the authenticated user. Allows editing all fields except contract_type.
Collection ID (uuid)
Updated collection details
Invalid request or ID format
Unauthorized (missing or invalid token)
Collection not found or access denied
Internal server error
PATCH /v1/nft/collections/{id} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 401
{
"description": "text",
"metadata": {
"base_token_uri": "text",
"custom_attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"external_url": "text",
"image_uri_pattern": "text",
"meta_description": "text",
"name_pattern": "text"
},
"mint_settings": {
"current_supply": 1,
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"symbol": "text"
}{
"chain_id": "text",
"contract_address": "text",
"contract_type": "text",
"created_at": "text",
"description": "text",
"id": "text",
"mint_settings": {
"current_supply": 1,
"is_public_mint": true,
"max_supply": 1,
"mint_price": 1,
"royalty_percentage": 1,
"royalty_recipient": "text"
},
"name": "text",
"network": "text",
"owner_address": "text",
"status": "text",
"symbol": "text",
"updated_at": "text",
"user_id": "text"
}Deletes a collection by ID, only if it belongs to the authenticated user and is in draft status.
Collection ID (uuid)
Successfully deleted
No content
Invalid ID format
Unauthorized (missing or invalid token)
Collection not found or access denied
Only draft collections can be deleted
Internal server error
DELETE /v1/nft/collections/{id} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
No content
Minting NFTs
Burning NFTs
Deploying Collections
Deploys a new NFT collection contract using the factory
Collection ID
Successfully deployed collection
Invalid collection ID or not deployable
Collection not found
Internal server error
POST /v1/nft/collections/{id}/deploy HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"contract_address": "text",
"explorer_url": "text",
"network": "text",
"status": "text",
"transaction_hash": "text"
}Estimating Deployment Cost
Estimates the gas cost for deploying an ERC721 collection contract
Collection ID
Successfully estimated deployment cost
Invalid collection ID
Collection not found
Internal server error
POST /v1/nft/collections/{id}/estimate HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"currency": "text",
"estimated_cost_eth": "text",
"estimated_cost_wei": "text",
"gas_estimate": 1,
"gas_price_wei": "text",
"network": "text"
}Verifying Contracts
Verifies the source code of a deployed contract on Etherscan testnet (sepolia) - DEPRECATED: This API is deprecated and will be removed in a future version
Collection ID
Successfully verified contract
Invalid collection ID
Collection not found
Internal server error
POST /v1/nft/collections/{id}/verify HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"contract_address": "text",
"explorer_url": "text",
"message": "text",
"success": true
}Metadata
Create a new metadata entry. Note: No need to call this endpoint manually. It is called automatically when an NFT is minted.
Creates a new metadata entry for a user. Accepts user_id (uuid), collection_id (uuid), nft_id (int), and data (arbitrary JSON) in the request body.
UUID of created metadata entry
Invalid request or validation error
POST /v1/nft/metadata HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"collection_id": "text",
"data": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"nft_id": 1,
"user_id": "text"
}{
"ANY_ADDITIONAL_PROPERTY": "text"
}Returns the raw JSON data for a metadata entry by collection_id (uuid) and NFT ID.
Collection ID (uuid)
NFT ID
Raw JSON data of the metadata entry
Metadata entry not found
GET /v1/nft/metadata/collection/{collection_id}/nft/{nft_id} HTTP/1.1
Host:
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}Health Check
How to Communicate with the Service
All endpoints are prefixed with
/v1/nft/.Use
Content-Type: application/jsonfor all requests.For authenticated endpoints, include the access token:
Authorization: Bearer <access_token>Follow the request/response examples above for each endpoint.
Refer swagger documentation if needed for api trials.
Security Tips
Verify NFT contract addresses before interacting or minting.
Beware of phishing sites and fake NFT collections.
Only use trusted wallets and marketplaces for NFT transactions.
Double-check transaction details before confirming any NFT mint.
Troubleshooting
Collection not found?
Check your collection ID and authentication token.
Minting failed?
Ensure the collection is deployed and you have sufficient balance.
Metadata not found?
Check the collection and NFT IDs.
Support & Contact
For help or to report issues, contact: [email protected]
For technical API questions, see the Swagger docs or contact your system administrator.
FAQ
Q: Can I use ERC-1155 collections? A: Not yet. Only ERC-721 is supported for now.
Q: How do I deploy a collection? A: Use the deploy endpoint as described above.
Q: How do I mint NFTs? A: Use the mint endpoint with the required parameters.
Q: Which blockchain network is used in the development environment? A: The service uses the Sepolia Ethereum testnet for development and testing.
Q: Is my data secure? A: The service uses industry-standard security practices, including JWT authentication and secure contract deployment.
Q: Is gRPC supported? A: The gRPC server is a placeholder. Actual service implementation is pending. See test_docs.md for current status and future plans.
Enum Values Reference
Below are the allowed values for key enum fields used in the API. Use these values when creating or updating collections, or interpreting API responses.
Collection Status
draft: Collection is created but not yet ready for deployment or minting.pending: Collection is in a pending state (e.g., awaiting deployment or verification).deployed: Collection contract has been deployed to the blockchain.verified: Collection contract has been verified (e.g., on Etherscan).archived: Collection is archived and not active.failed: Deployment or another operation failed for this collection.
Contract Type
ERC-721: Standard NFT contract (currently supported)ERC-1155: Multi-token standard (not yet supported)
Network
ethereum: Ethereum mainnet or testnet (currently supported)polygon: Polygon network (not yet supported)
Storage Method
ipfs: Metadata and assets are stored on IPFS (currently supported)api: Metadata is stored via the platform API (currently supported)on_chain: Metadata is stored directly on-chain (not yet supported)
Note: Only the values marked as "currently supported" are accepted by the API at this time. Others are reserved for future use and will result in errors if used.
Notes
All tests assume the development environment is running:
docker-compose --profile dev up -dgRPC port 9093 is currently running a placeholder server
Actual gRPC service implementation is pending
Hot reload functionality may require specific Colima configuration on Apple Silicon Macs
Last updated
Was this helpful?