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>

---

List NFT collections (paginated, user-only)

get

Returns a paginated list of NFT collections belonging to the authenticated user only.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Query parameters

limitintegerOptional

Number of items per page (default 10)

pageintegerOptional

Page number (default 1)

Responses

200

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

application/json

400

Invalid query parameters

application/json

401

Unauthorized (missing or invalid token)

application/json

500

Internal server error

application/json

get

/v1/nft/collections

HTTPcURLJavaScriptPython

GET /v1/nft/collections HTTP/1.1
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
}

Create a new NFT collection

post

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: Set to desired percentage (e.g., 2.5 for 2.5%). Set to 0 or omit for no royalties.

• Royalty recipient: Ethereum address to receive royalties. Required if royalty_percentage > 0.

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.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Body

application/json

contract_typestringRequired

descriptionstringOptional

namestringRequired

networkstringRequired

owner_addressstringRequired

storage_methodstringRequired

symbolstringRequired

Responses

201

Successfully created collection

application/json

400

Invalid request parameters" "{"error": "Invalid request parameters"}

application/json

500

Internal server error" "{"error": "Internal server error"}

application/json

post

/v1/nft/collections

HTTPcURLJavaScriptPython

POST /v1/nft/collections HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "contract_type": "text",
  "description": "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",
  "contract_address": "text",
  "contract_type": "text",
  "created_at": "text",
  "deleted_at": "text",
  "description": "text",
  "id": "text",
  "ipfs_root_cid": "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",
  "owner_address": "text",
  "status": "text",
  "storage_method": "text",
  "symbol": "text",
  "transaction_hash": "text",
  "updated_at": "text",
  "user_id": "text"
}

Get a single NFT collection (auth user only)

get

Returns a single NFT collection by ID, only if it belongs to the authenticated user.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstringRequired

Collection ID (uuid)

Responses

200

Collection details (same fields as list)

application/json

400

Invalid ID format

application/json

401

Unauthorized (missing or invalid token)

application/json

404

Collection not found or access denied

application/json

500

Internal server error

application/json

get

/v1/nft/collections/{id}

HTTPcURLJavaScriptPython

GET /v1/nft/collections/{id} HTTP/1.1
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"
}

Update a single NFT collection (auth user only)

patch

Partially updates a single NFT collection by ID, only if it belongs to the authenticated user. Allows editing all fields except contract_type.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstringRequired

Collection ID (uuid)

Body

application/json

descriptionstringOptional

namestringOptional

networkstringOptional

symbolstringOptional

Responses

200

Updated collection details

application/json

400

Invalid request or ID format

application/json

401

Unauthorized (missing or invalid token)

application/json

404

Collection not found or access denied

application/json

500

Internal server error

application/json

patch

/v1/nft/collections/{id}

HTTPcURLJavaScriptPython

PATCH /v1/nft/collections/{id} HTTP/1.1
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"
}

---

Delete a collection (auth user only, only if status is draft)

delete

Deletes a collection by ID, only if it belongs to the authenticated user and is in draft status.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstringRequired

Collection ID (uuid)

Responses

204

Successfully deleted

400

Invalid ID format

application/json

401

Unauthorized (missing or invalid token)

application/json

404

Collection not found or access denied

application/json

409

Only draft collections can be deleted

application/json

500

Internal server error

application/json

delete

/v1/nft/collections/{id}

HTTPcURLJavaScriptPython

DELETE /v1/nft/collections/{id} HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

No content

Minting NFTs

---

Burning NFTs

---

Deploying Collections

Deploy a collection contract

post

Deploys a new NFT collection contract using the factory

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstring · uuidRequired

Collection ID

Responses

200

Successfully deployed collection

application/json

400

Invalid collection ID or not deployable

application/json

404

Collection not found

application/json

500

Internal server error

application/json

post

/v1/nft/collections/{id}/deploy

HTTPcURLJavaScriptPython

POST /v1/nft/collections/{id}/deploy HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

{
  "contract_address": "text",
  "explorer_url": "text",
  "network": "text",
  "status": "text",
  "transaction_hash": "text"
}

---

Estimating Deployment Cost

Estimate deployment cost for a collection

post

Estimates the gas cost for deploying an ERC721 collection contract

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstring · uuidRequired

Collection ID

Responses

200

Successfully estimated deployment cost

application/json

400

Invalid collection ID

application/json

404

Collection not found

application/json

500

Internal server error

application/json

post

/v1/nft/collections/{id}/estimate

HTTPcURLJavaScriptPython

POST /v1/nft/collections/{id}/estimate HTTP/1.1
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

Deprecated

Verify a deployed contract on Etherscan testnet (sepolia)

post

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

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstring · uuidRequired

Collection ID

Responses

200

Successfully verified contract

application/json

400

Invalid collection ID

application/json

404

Collection not found

application/json

500

Internal server error

application/json

post

/v1/nft/collections/{id}/verify

HTTPcURLJavaScriptPython

POST /v1/nft/collections/{id}/verify HTTP/1.1
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.

post

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.

Body

application/json

collection_idstringRequired

nft_idintegerRequired

user_idstringRequired

Responses

201

UUID of created metadata entry

application/json

400

Invalid request or validation error

application/json

post

/v1/nft/metadata

HTTPcURLJavaScriptPython

POST /v1/nft/metadata HTTP/1.1
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"
}

Get metadata entry by collection and NFT ID

get

Returns the raw JSON data for a metadata entry by collection_id (uuid) and NFT ID.

Path parameters

collection_idstringRequired

Collection ID (uuid)

nft_idintegerRequired

NFT ID

Responses

200

Raw JSON data of the metadata entry

application/json

404

Metadata entry not found

application/json

get

/v1/nft/metadata/collection/{collection_id}/nft/{nft_id}

HTTPcURLJavaScriptPython

GET /v1/nft/metadata/collection/{collection_id}/nft/{nft_id} HTTP/1.1
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

---

Health Check

Health Check

get

Returns the health status of the service and its dependencies

Responses

200

OK

application/json

get

/v1/nft/health

HTTPcURLJavaScriptPython

GET /v1/nft/health HTTP/1.1
Accept: */*

200

OK

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

---

How to Communicate with the Service

• All endpoints are prefixed with /v1/nft/.

• Use Content-Type: application/json for 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 -d

• gRPC 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