Refs

A Ref is a reference to an IYK tap instance.

Get a ref

Fetch information for a given ref.

If isValidRef is true, returns OTP codes that can be used to transfer the linked NFT and access any available modules. Note that by default, OTP codes expire in 30 minutes.

When querying refs from chip redirects, do not provide an API key. However, if you're querying a ref from the Links Module, you must provide an API key to recieve valid refs.

Refs are valid the first time they are queried. Any subequent queries will return isValidRef: false and not return any OTP codes. This behavior allows you to have replay protection in your frontend page, preventing a page from being shared.

Request

GET /refs/:id

Headers

Header	Description	Required
`x-iyk-api-key`	API key for user	No (see note above)

Search Parameters

Field	Type	Description	Required
`includeOwner`	`boolean`	Include the address of the token owner	No
`includeMetadata`	`boolean`	Include the token metadata	No

Response

{
  "uid": "1111111111144444",
  "isValidRef": false,
  "linkedToken": {
    "contractAddress": "0x067f20be8e84c8fed733578e7249ea911111111",
    "chainId": 1,
    "tokenId": "1",
    "otp": "unique-21char-Nano_Id",
    "ownerAddress": "0x57cE8c50Fb287C94a1190565aFeEC56EC3cD2c0D",
    "metadata": {
      "description": "Friendly OpenSea Creature that enjoys long swims in the ocean.",
      "external_url": "https://openseacreatures.io/3",
      "image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
      "name": "Dave Starbelly",
      "attributes": [
        {
          "trait_type": "Base",
          "value": "Starfish"
        },
        {
          "trait_type": "Eyes",
          "value": "Big"
        }
      ]
    }
  },
  "poapEvents": [
    {
      "id": 1,
      "poapEventId": 123456,
      "otp": "unique-21char-Nano_Id",
      "status": "active"
    }
  ]
}

Field	Description	Type
`uid`	UniversalID of the chip	`string`
`isValidRef`	The first time you query for a ref this will be `true`. Every subsequent query for the ref will return `false`. This behavior allows you to have replay protection in your frontend page.	`boolean`
`linkedToken`	If the chip is linked to a Digital Twin NFT, this node provides a `TokenRef`.	`TokenRef?`
`linkedToken.otp`	OTP code to be used when transferring this NFT. Only returned if `isValidRef` is `true`.	`string?`
`linkedToken.ownerAddress`	The address of the token owner. Only returned if `includeOwner` is `true`.	`string?`
`linkedToken.metadata`	The OpenSea ERC721 metadata standard. Only returned if `includeMetadata` is `true`.	`Metadata?`
`poapEvents`	Any active POAP events linked to this chip.	`array`
`poapEvents[].id`	IYK ID of the POAP event. Use this for making queries against IYK's API.	`number`
`poapEvents[].poapEventId`	POAP ID of the POAP event. Use this for making queries against the POAP API.	`number`
`poapEvents[].otp`	OTP code to be used when minting a POAP for this event. Only returned if `isValidRef` is `true`.	`string?`
`poapEvents[].status`	Status of the POAP event ("pending-approval", "future", "active", "expired", "rejected")	`StatusEnum`

Support for Third-Party Applications

IYK will pass third-party applications a reference corresponding to a specific tap instance.

The sequence looks roughly like:

Person taps a chip
IYK renders tap page if link is valid
IYK can redirect or link out to a registered third party baseURL with an iykRef query parameter
- For example, https://example.com/foo?iykRef=123
The third party app developer can then query the /refs/:id endpoint with their api key in order to determine if the link is valid and retrieve information on the chip
The third party app developer can then use OTP codes returned on other relevant API calls via a x-iyk-code header

Items OTP Codes