FINGI API endpoints

To understand how to start using FINGI API, please address following sections of our documentation:
1. How to use FINGI API
2. How to Create App
3. How to Get API Key

tl;dr; you don't want to keep FINGI API keys in your client-side code as well as user inventory management to avoid possible cheating and doubling of virtual assets. Keep these server-side and everything should be fine. 😉

API Request Authorization Header

Every HTTP request to FINGI API has to authorized with FINGI API Key. You can find it or generate a new one at the bottom "Edit App" page.

HEADER	VALUE
Authorization	Bearer Your_Fingi_Api_Key_Here

GET https://fingi-api.fingistore.workers.dev/api/pull_items

This API endpoint allows you to pull items from FINGI to get the current status of a user's inventory and update the in-game or in-app inventory state. It is useful to call this endpoint before users interact with their inventory or at the start of the client to ensure the inventory is up-to-date.

Request query parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page.
userEmail	string	(Required) User's personal account email.

Response Fields

Parameter	Type	Description
items	Item[]	Array of user items in FINGI inventory

Response Item Object

Parameter	Type	Description
itemOwner	string	Email of item owner
clientId	string	App client id
itemUri	string	Item metadata URL
itemType	number	Item type (0, 1, 2)
itemCount	number	Number of items in inventory
timeLimit	number \| null	Time Limit for items of itemType=2

Sample request


  curl \
  -X GET \
  -H "Authorization Bearer MTgx..." \
  https://fingi-api.fingistore.workers.dev/api/pull_items?clientId=321&[email protected]

Sample response


  {
    "items":[
      {
        "itemOwner":"[email protected]",
        "clientId":"321",
        "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=123123",
        "itemType":1,
        "itemCount":361,
        "timeLimit":null
      },
      {
        "itemOwner":"[email protected]",
        "clientId":"321",
        "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=123",
        "itemType":0,
        "itemCount":253,
        "timeLimit":null
      },
      {
        "itemOwner":"[email protected]",
        "clientId":"321",
        "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
        "itemType":2,
        "itemCount":716,
        "timeLimit":270000
      },
      ...
    ]
  }

POST https://fingi-api.fingistore.workers.dev/api/push_items

Push items to FINGI database when users update their inventory. This will completely overwrite the state of the users inventory for the specified ClientId.

Request body parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page
userEmail	string	(Required) User personal account email
items	PushItem[] \| null	(Optional) User items in inventory to synchronize with FINGI. This request will wipe items in FINGI inventory if null is sent

Push Item Object

Parameter	Type	Description
itemUri	string	Item metadata URL
itemCount	number	Number of items in user inventory
itemType	number	Item type (0, 1, 2)
timeLimit	number \| null	Time Limit for items of itemType=2

Response

Parameter	Type	Description
pushedItems	Item[]	Current state of the users inventory on FINGI

Sample request


  curl \
  -X POST \
  -H "Authorization Bearer MTgx..." \
  -d '{"clientId":"321","userEmail":"[email protected]","items":[{
    "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
    "itemType":2,
    "itemCount":800,
    "timeLimit":270000
  }]}'
  https://fingi-api.fingistore.workers.dev/api/push_items

Sample response


{
  "pushedItems":[
    {
      "itemOwner":"[email protected]",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
      "clientId":"321",
      "itemCount":800,
      "itemType":2,
      "timeLimit":270000
    }
    ...
  ]
}

GET https://fingi-api.fingistore.workers.dev/api/peek_merge_pending

Get the list of items to be merged into users in-app or in-game inventory. This is a list of mergeable items (itemType=1). These item merges appear after burning tokens and cancelling sell orders. Permanent and time-limited items will not be displayed here.

Request query parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page
userEmail	string	(Required) User personal account email

Response Fields

Parameter	Type	Description
merges	ItemMerge[]	Array of items to be merged into users in-game or in-game inventory

Response Item Merge

Parameter	Type	Description
mergeId	string	Item merge Id. Use it in merge request
itemUri	string	Item metadata URL
clientId	string	App client id
itemAcquirer	string	Email of item acquirer (user to receive this merge)
sellCount	number	Number of items to be merged
itemType	number	Item type (0, 1, 2)
timeLimit	number \| null	Time Limit for items of itemType=2

Sample request


curl \
-X GET \
-H "Authorization Bearer MTgx..." \
https://fingi-api.fingistore.workers.dev/api/peek_merge_pending?clientId=321&[email protected]

Sample response


{
  "merges":[
    {
      "mergeId":"345036023971971659",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
      "clientId":"321",
      "itemAcquirer":"[email protected]",
      "sellCount":50,
      "itemType":2,
      "timeLimit":270000
    },
    {
      "mergeId":"345036289988362828",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=123123",
      "clientId":"321",
      "itemAcquirer":"[email protected]",
      "sellCount":1,
      "itemType":1,
      "timeLimit":0
    },
    {
      "mergeId":"345036307402064457",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=123",
      "clientId":"321",
      "itemAcquirer":"[email protected]",
      "sellCount":3,
      "itemType":0,
      "timeLimit":null
    },
    ...
  ]
}

POST https://fingi-api.fingistore.workers.dev/api/merge_items

Merge some items with specified merge ids and amounts. Calling this API will subract the Amount of items from the selected MergeId. Items that are not merged fully will stay in the merge list until they are merged completely. Call this method AFTER you picked items to be merged from /peek_merge_pending. This means that you add these items to the inventory on your server and then call this method to remove these items from the Merge section of FINGI to avoid merging them again.

Request body parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page
userEmail	string	(Required) User personal account email
data	MergeInput[] \| null	(Optional) Items that have been merged from FINGI merge section.

Merge Input Object

Parameter	Type	Description
mergeId	string	Id of the Item Merge
amount	number	Amount of items selected to be merged into inventory

Response

Parameter	Type	Description
mergedItems	ItemMerge[]	The remaining Item Merge Objects with selected ids that did not merge completely. Empty if all merges were complete.

Sample request


  curl \
  -X POST \
  -H "Authorization Bearer MTgx..." \
  -d '{"clientId":"321","userEmail":"[email protected]","data":[{
    "mergeId":"345036023971971659",
    "amount":32
    }]}'
  https://fingi-api.fingistore.workers.dev/api/merge_items

Sample response


{
  "mergedItems":[
    {
      "mergeId":"345036023971971659",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
      "clientId":"321",
      "itemAcquirer":"[email protected]",
      "sellCount":18
    }
    ...
  ]
}

GET https://fingi-api.fingistore.workers.dev/api/owned_tokens

Get the list of permanent items (itemType=0), stored in user wallet. These items may not be lost or spent inside the game or app. Users will have access to it as long as tokens are inside their wallet.

Request query parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page
userEmail	string	(Required) User personal account email

Response Fields

Parameter	Type	Description
tokens	Token[]	Array of tokenized items itemType=0 in users crypto wallet associated with his email

Response Token Object

Parameter	Type	Description
tokenId	string	Item Token Id as it is on blockchain
itemUri	string	Item metadata URL
clientId	string	App client id
tokenOwner	string	Email of token owner
tokenCount	number	Number of tokens in wallet

Sample request


curl \
-X GET \
-H "Authorization Bearer MTgx..." \
https://fingi-api.fingistore.workers.dev/api/owned_tokens?clientId=321&[email protected]

Sample response


{
  "tokens":[
    {
      "tokenId":"0",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=123",
      "clientId":"321",
      "tokenOwner":"[email protected]",
      "tokenCount":24
    },
    ...
  ]
}

GET https://fingi-api.fingistore.workers.dev/api/active_subs

Get the list of activated time-limited items (itemType=2) with the expiration date.

Request query parameters

Parameter	Type	Description
clientId	string	(Required) App client id. You can find it at the top of Edit App page
userEmail	string	(Required) User personal account email

Response Fields

Parameter	Type	Description
subs	Subscription[]	Array of activated time-limited items itemType=2 in users crypto wallet associated with his email

Response Subsciption Object

Parameter	Type	Description
tokenId	string	Item Token Id as it is on blockchain
itemUri	string	Item metadata URL
clientId	string	App client id
tokenOwner	string	Email of token owner
expirationDate	number	token expiration date in seconds (Unix Timestamp)
isActive	boolean	token active period is not expired

Sample request


curl \
-X GET \
-H "Authorization Bearer MTgx..." \
https://fingi-api.fingistore.workers.dev/api/active_subs?clientId=321&[email protected]

Sample response


{
  "subs":[
    {
      "tokenId":"0",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
      "clientId":"321",
      "tokenOwner":"[email protected]",
      "expirationDate":1667642342,
      "isActive":false
    },
    {
      "tokenId":"1",
      "itemUri":"https://sample-fingi-game.fingistore.workers.dev/item?id=15",
      "clientId":"321",
      "tokenOwner":"[email protected]",
      "expirationDate":1667752112,
      "isActive":true
    },
    ...
  ]
}