Metafile Index Service

Metafile Index ServiceAPIServer InfoQuery FileQuery ChunkCreate FileUpdate ChunkResponse CodeDownload FileService FeeClient FlowExample 1Example 2SDKContact

logo

API

Endpoint https://metafile.id

Server Info

GET /info

Response HTTP 200


{
    "code":0,
    "message":"Welcome to use Metafile.ID - the index service for metafile on Bitcoin SV!",
    "email":"[email protected]",
    "service_fee_address":"1KGrWHSS5WhidvwLY1q7UBiJSqahvt4LEb",
    "service_fee_rate":0.025,
    "service_fee_min_satoshis":996
}

Query File

GET /v1/files/<file_id>

GET /v1/files/query?sha256=<sha256>&metaid=<metaid>

Response HTTP 200


{
   "code":0,
   "message":"OK",
   "id":"bc2288be78904d8dbd9e5cdd3e9dcf04",
   "size":204800,
   "sha256":"3d0e50ecafcf6bf81d5f67462b117068d6b94cfa29b5f5fc2ee629ef5a14974d",
   "metaid":"b89840e798b334e4f2d5279b6a325b411125e927f2dba16af4208d827ede8e11",
   "name":"NQwysRmbOY.txt",
   "mime":"text/plain",
   "txid":null,
   "chunk_size":102400,
   "chunks":2,
   "chunks_all_ready":false,
   "chunk_list":[
      {
         "sequence":2,
         "sha256":"3aeefa870ac3c597d5d6d526d7fdf7289f07abeb81c71d38a4540d54105730ae",
         "txid":"dfd01babca9d23cc357ef29ed038c8fbdca354a31e3e4ce4d789064d58b14664"
      }
   ]
}


{
   "code":0,
   "message":"OK",
   "id":"74d0d51e2e2f401195042f7aa43fc78e",
   "size":248641,
   "sha256":"b13a3d74aabc65134dd9526ebe64b4f61079532bcae334340d3e03a1e3b10e15",
   "metaid":"b89840e798b334e4f2d5279b6a325b411125e927f2dba16af4208d827ede8e11",
   "name":"hello.jpg",
   "mime":"image/jpeg",
   "txid":"82547588dbc6b6e92626eb3567a1a61b7918119d95bf99fbb99c927515983452",
   "chunk_size":102400,
   "chunks":3,
   "chunks_all_ready":true,
   "chunk_list":[
      {
         "sequence":1,
         "sha256":"c66acef339b85bb130cfda3954489ca532c2f3ee053c69e9256c12029984a56d",
         "txid":"8b88c31d3960fd52c0a7a74284b41e1c9df7243aee29aac8e1150e5d7e6fba4f"
      },
      {
         "sequence":2,
         "sha256":"c7c7163cc93dc4d66b935dac898a3513fefa9bc6797b48bc48116cc57f2b0a37",
         "txid":"571916fbec937a41a9974cbc9448e781f9ff0b201370b9de92bd221ac476ad0c"
      },
      {
         "sequence":3,
         "sha256":"cd4d70a4cceda331c6c62f7574b17bcfa73bb7409bb1bac154a5b1e63008c623",
         "txid":"098c51291fcd3f070ca19487dd19ae3e3842d3d7376d936ed5e6af0ba4c4d2d6"
      }
   ]
}

Query Chunk

GET /v1/chunks/<file_id>/<chunk_sequence>

GET /v1/chunks/query?sha256=<sha256>

Response HTTP 200


{
   "code":0,
   "message":"OK",
   "sha256":"cd4d70a4cceda331c6c62f7574b17bcfa73bb7409bb1bac154a5b1e63008c623",
   "txid":"098c51291fcd3f070ca19487dd19ae3e3842d3d7376d936ed5e6af0ba4c4d2d6"
}

Create File

POST /v1/files

Request body application/json

Keys	Type	Description
size	int	File size in bytes
sha256	string	File SHA-256 hash
metaid	string	User MetaID
name	string	File name
data_type	string	File MIME

Response HTTP 200

Keys	Type	Description
code	int	Response code
message	string	Server message
file_id	string	Server unique ID for this file
chunks	int	How many chunks should this file be separated into
chunk_size	int	Chunk max length in bytes


{
   "code":0,
   "message":"OK",
   "file_id":"bc2288be78904d8dbd9e5cdd3e9dcf04",
   "chunks":2,
   "chunk_size":102400
}

Update Chunk

POST /v1/chunks

Request body application/json

size	int	File size in bytes
file_id	string	File unique ID
chunk_sequence	int	Sequence number of the chunk, 0 means update file index or metafile in legacy format
sha256	string	SHA-256 hash of the chunk or the file index
txid	string	metafile/chunk transaction if chunk_sequence = 1, 2, 3... metafile/index or legacy metafile transaction if chunk_sequence = 0

Response HTTP 200

Keys	Type	Description
code	int	Response code
message	string	Server message
txid	string	The txid to index this chunk (chunk_sequence = 1, 2, 3...) or the file (chunk_sequence = 0)


{
   "code":0,
   "message":"OK",
   "txid":"dfd01babca9d23cc357ef29ed038c8fbdca354a31e3e4ce4d789064d58b14664"
}

Response Code

Response Code	Description
0	OK
10	Unknown exception
20	Bad request, parameter type mismatch or missing required fields
30	File not found
31	The file has finished upload before and cannot be modified
32	Invalid chunk sequence
33	Chunk not found
34	File hash mismatch
35	Chunk hash mismatch
36	Bad transaction
37	Bad chunk index payload

Download File

https://metafile.id/download/<txid>

Service Fee

The query service is currently FREE, but there is a charge for creating a new index.

When requesting Update Chunk API to log your file, we require every metafile/chunk and metafile/index transaction has a P2PKH service fee output.

Let's say, the size of all the OP_RETURN pushdata is S bytes (only the data, excluding OP_CODES), then you need to pay at least


max(service_fee_min_satoshis, math.floor(S * service_fee_rate))

satoshis to our service_fee_address. The value of service fee parameters can be found here.

Example, if service_fee_min_satoshis is 996 and service_fee_rate is 0.025.

For transaction 098c51291fcd3f070ca19487dd19ae3e3842d3d7376d936ed5e6af0ba4c4d2d6, the size of all the OP_RETURN pushdata is 44073 bytes, then the service fee would be


max(996, math.floor(44073 * 0.025)) = max(996, 1101) = 1101

For transaction 1bfb803342f1958612b943aa599667339a12b61fbffb95d17770493e458b212d, the size of all the OP_RETURN pushdata is 728 bytes, then the service fee would be


max(996, math.floor(728 * 0.025)) = max(996, 18) = 996

Client Flow

Example 1

File pxtYFBwYYH.txt has 102402 bytes, the chunk size is 102400 bytes, so separate it into 2 chunks.

Then there are 3 transactions associated with this file.

Chunk #1 3f0bc76356b514450adc38f8487c38a9a5e443633d8928213655f591e1f9168d, metafile/chunk transaction, upload the first 102400 bytes of file
Chunk #2 c3ead041ef386dc42054c77b20f80eb8c7723f1e1bf0ebb35cfa84f25d6acc57, metafile/chunk transaction, upload the last 2 bytes of file
Chunk #0 14aac6337f517b238e3d950f2366f35dd5ba3698a19c57129ec0915cb2045823, metafile/index transaction, upload the following file index


{
    "sha256":"030b013529b6d1837b567e2bfce159ca34eb2d720bd1af5fb5bde4d3fbe2bcd8",
    "fileSize":102402,
    "chunkNumber":2,
    "chunkSize":102400,
    "dataType":"text/plain",
    "name":"pxtYFBwYYH.txt",
    "chunkList":[
        {
            "sha256":"423ab467dcb72ef1de136e151a90fa20f22f28482d4efc4c4f893ae0faa7b368",
            "txid":"3f0bc76356b514450adc38f8487c38a9a5e443633d8928213655f591e1f9168d"
        },
        {
            "sha256":"b2608d57488c00156d82401ba5114dc1eddbae104173c08bfa061c1a24019423",
            "txid":"c3ead041ef386dc42054c77b20f80eb8c7723f1e1bf0ebb35cfa84f25d6acc57"
        }
    ]
}

Query response of this file:


{
    "code":0,
    "message":"OK",
    "id":"19060aa4577c45d88f25e776e8e1679c",
    "size":102402,
    "sha256":"030b013529b6d1837b567e2bfce159ca34eb2d720bd1af5fb5bde4d3fbe2bcd8",
    "metaid":"b89840e798b334e4f2d5279b6a325b411125e927f2dba16af4208d827ede8e11",
    "name":"pxtYFBwYYH.txt",
    "mime":"text/plain",
    "txid":"14aac6337f517b238e3d950f2366f35dd5ba3698a19c57129ec0915cb2045823",
    "chunk_size":102400,
    "chunks":2,
    "chunks_all_ready":true,
    "chunk_list":[
        {
            "sequence":1,
            "sha256":"423ab467dcb72ef1de136e151a90fa20f22f28482d4efc4c4f893ae0faa7b368",
            "txid":"3f0bc76356b514450adc38f8487c38a9a5e443633d8928213655f591e1f9168d"
        },
        {
            "sequence":2,
            "sha256":"b2608d57488c00156d82401ba5114dc1eddbae104173c08bfa061c1a24019423",
            "txid":"c3ead041ef386dc42054c77b20f80eb8c7723f1e1bf0ebb35cfa84f25d6acc57"
        }
    ]
}

Example 2

File vobeLfOHBx.txt has 512 bytes which is less than the chunk size, so no need to separate, use legacy metafile format.

Then there is only 1 transaction associated with this file.

Chunk #0 085ea634ab7b3cabc89d91ed8f7b69d0f54b4ac789832ab6e99fa34d7faa29b2, legacy metafile transaction, upload the whole file

Query response of this file:


{
    "code":0,
    "message":"OK",
    "id":"130282928ee54241b0a6bb0e2d327b3a",
    "size":512,
    "sha256":"b76fe1b4b3263eeaf653a6ade1510834979773d0ec5c568223af9a2613f814f7",
    "metaid":"b89840e798b334e4f2d5279b6a325b411125e927f2dba16af4208d827ede8e11",
    "name":"vobeLfOHBx.txt",
    "mime":"text/plain",
    "txid":"085ea634ab7b3cabc89d91ed8f7b69d0f54b4ac789832ab6e99fa34d7faa29b2",
    "chunk_size":102400,
    "chunks":0,
    "chunks_all_ready":true,
    "chunk_list":[]
}

SDK

Python >= 3.6

Contact

Join our Telegram group or email [email protected] 🚀