Phygitals

A Phygital is a reference to an IYK-managed NFT connected to an NFC chip.

Transfer Ownership with API key

Allows token transfers via API key and valid phygital (linkedToken) token reference (from GET /refs/:id).

Request

POST /phygitals/transfer

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-api-key`	API key for user	Yes

Body

Field	Description	Type
`contractAddress`	Contract address of the token	`string`
`chainId`	Chain ID of the network where the token resides	`number`
`tokenId`	ID of the token	`string`
`recipient`	ETH address or ENS name to transfer ownership to	`string`

Response

{
  "success": true,
  "initialTxHash": "0x07d1953bc13656004bf407b93f65b6a3d178b473ccc74594e2780bbd62f920d6"
}

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`initialTxHash`	The transaction hash for the ownership transfer. In rare cases this hash may change as the transaction is resubmitted by the relayer.	`string`

Transfer Ownership with OTP code

Allows token transfers via OTP code. For tokens using 2-Tap claim (opens in a new tab), please refer to the claim-registration endpoints for setting up ownership transfer.

Request

POST /phygitals/transfer/pullable

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-code`	OTP code for token	Yes

Body

Field	Description	Type
`recipient`	ETH address or ENS name to transfer ownership to	`string`

Response

{
  "success": true,
  "initialTxHash": "0x07d1953bc13656004bf407b93f65b6a3d178b473ccc74594e2780bbd62f920d6"
}

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`initialTxHash`	The transaction hash for the ownership transfer. In rare cases this hash may change as the transaction is resubmitted by the relayer.	`string`

Get Transfer Signature with API Key

Generates a transfer signature using an API key. This signature can be passed into mintNFT or claimNFT to transfer the associated token to the given recipient.

Request

GET /phygitals/transfer-signature

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-api-key`	API key for user	Yes

Request Body

Parameter	Description	Type	Required
`contractAddress`	Contract address of the token	`string`	Yes
`chainId`	Chain ID of the network where the token resides	`number`	Yes
`tokenId`	ID of the token	`string`	Yes
`recipient`	ETH address or ENS name to transfer ownership to	`string`	Yes

Response

{
  "signature": "0xSignature",
  "blockExpiry": "12345678",
  "tokenRef": {
    "contractAddress": "0xContractAddress",
    "tokenId": "1234",
    "chainId": "1"
  }
}

Field	Description	Type
`signature`	The signature generated for the transfer	`string`
`blockExpiry`	Block number when the signature expires	`string`

Get Transfer Signature with OTP Code

Generates a transfer signature using an OTP code. This signature can be passed into mintNFT or claimNFT to transfer the associated token to the given recipient.

Request

GET /phygitals/transfer-signature/pullable

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-code`	OTP code for token	Yes

Request Body

Parameter	Description	Type	Required
`recipient`	ETH address or ENS name to transfer ownership to	`string`	Yes

Response

{
  "signature": "0xSignature",
  "blockExpiry": "12345678",
  "tokenRef": {
    "contractAddress": "0xContractAddress",
    "tokenId": "1234",
    "chainId": "1"
  }
}

Field	Description	Type
`signature`	The signature generated for the transfer	`string`
`blockExpiry`	Block number when the signature expires	`string`
`tokenRef.contractAddress`	Contract address of the token	`string`
`tokenRef.tokenId`	ID of the token	`string`
`tokenRef.chainId`	Chain ID of the network where the token resides	`string`

Get Linked Chip

Get the chip linked to a token.

Request

GET /phygitals/chip

Query Params

Parameter	Description	Required
`contractAddress`	Contract address of the token	Yes
`chainId`	Chain ID of the network where the token resides	Yes
`tokenId`	ID of the token	Yes

Response

{
  "uid": "1111111111144444"
}

Field	Description	Type
`uid`	UID of the chip	`string`

Get Claim Registration

Get the claim registration status for a token.

Request

GET /phygitals/claim-registration

Query Params

Parameter	Description	Required
`contractAddress`	Contract address of the token	Yes
`chainId`	Chain ID of the network where the token resides	Yes
`tokenId`	ID of the token	Yes
`recipient`	ETH address or ENS name to transfer ownership to	Yes

Response

{
  "recipient": "0xRecipientAddress",
  "linkedToken": {
    "contractAddress": "0xContractAddress",
    "tokenId": "1234",
    "chainId": "1"
  },
  "isRequired": true,
  "isValid": false,
  "allowedAt": "2023-01-01T00:00:00Z",
  "expiresAt": "2023-01-02T00:00:00Z",
  "createdAt": "2023-01-01T00:00:00Z"
}

Field	Description	Type
`recipient`	ETH address or ENS name of the recipient	`string`
`linkedToken`	Object containing details about the linked token	`object`
`linkedToken.contractAddress`	Contract address of the token	`string`
`linkedToken.tokenId`	ID of the token	`string`
`linkedToken.chainId`	Chain ID of the network where the token resides	`string`
`isRequired`	Indicates if claim registration is required. If false, proceed with transfer.	`boolean`
`isValid`	Indicates if the claim registration is valid. If true, proceed with transfer.	`boolean`
`allowedAt`	Date and time when the claim registration is allowed	`string` (ISO 8601)
`expiresAt`	Date and time when the claim registration expires	`string` (ISO 8601)
`createdAt`	Date and time when the claim registration was created	`string` (ISO 8601)

Add Claim Registration with API key

Create a claim registration for a token via API key.

Request

POST /phygitals/claim-registration

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-api-key`	API key for user	Yes

Request Body

Field	Description	Type	Required
`contractAddress`	Contract address of the token	`string`	Yes
`chainId`	Chain ID of the network where the token resides	`number`	Yes
`tokenId`	ID of the token	`string`	Yes
`recipient`	ETH address or ENS name to transfer ownership to	`string`	Yes

Example Request Body

{
  "contractAddress": "0x17827126bda4a649b578191ff17275fdd6a20167",
  "chainId": 137,
  "tokenId": "3",
  "recipient": "0xRecipientAddressOrENS"
}

Response

{
  "recipient": "0xRecipientAddressOrENS",
  "linkedToken": {
    "contractAddress": "0xContractAddress",
    "tokenId": "1234",
    "chainId": "1"
  },
  "allowedAt": "2023-01-01T00:00:00Z",
  "expiresAt": "2023-01-02T00:00:00Z",
  "createdAt": "2023-01-01T00:00:00Z"
}

Field	Description	Type
`recipient`	ETH address or ENS name of the recipient	`string`
`linkedToken`	Object containing details about the linked token	`object`
`linkedToken.contractAddress`	Contract address of the token	`string`
`linkedToken.tokenId`	ID of the token	`string`
`linkedToken.chainId`	Chain ID of the network where the token resides	`string`
`allowedAt`	Date and time when the claim registration is allowed	`string` (ISO 8601)
`expiresAt`	Date and time when the claim registration expires	`string` (ISO 8601)
`createdAt`	Date and time when the claim registration was created	`string` (ISO 8601)

Add Claim Registration with OTP code

Create a claim registration for a token using a claim code.

Request

POST /phygitals/claim-registration/pullable

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-code`	OTP code for token	Yes

Request Body

Field	Description	Type	Required
`recipient`	ETH address or ENS name to transfer ownership to	`string`	Yes

Example Request Body

{
  "recipient": "0xRecipientAddressOrENS"
}

Response

{
  "recipient": "0xRecipientAddressOrENS",
  "linkedToken": {
    "contractAddress": "0xContractAddress",
    "tokenId": "1234",
    "chainId": "1"
  },
  "allowedAt": "2023-01-01T00:00:00Z",
  "expiresAt": "2023-01-02T00:00:00Z",
  "createdAt": "2023-01-01T00:00:00Z"
}

Field	Description	Type
`recipient`	ETH address or ENS name of the recipient	`string`
`linkedToken`	Object containing details about the linked token	`object`
`linkedToken.contractAddress`	Contract address of the token	`string`
`linkedToken.tokenId`	ID of the token	`string`
`linkedToken.chainId`	Chain ID of the network where the token resides	`string`
`allowedAt`	Date and time when the claim registration is allowed	`string` (ISO 8601)
`expiresAt`	Date and time when the claim registration expires	`string` (ISO 8601)
`createdAt`	Date and time when the claim registration was created	`string` (ISO 8601)

Delete Claim Registration with API key

Deletes a claim registration for a token and recipient via API key.

Request

DELETE /phygitals/claim-registration

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-api-key`	API key for user	Yes

Request Body

Field	Description	Type	Required
`contractAddress`	Contract address of the token	`string`	Yes
`chainId`	Chain ID of the network where the token resides	`number`	Yes
`tokenId`	ID of the token	`string`	Yes
`recipient`	ETH address or ENS name to transfer ownership to	`string`	Yes

Example Request Body

{
  "contractAddress": "0x17827126bda4a649b578191ff17275fdd6a20167",
  "chainId": 137,
  "tokenId": "3",
  "recipient": "0xRecipientAddressOrENS"
}

Response

{
  "success": true
}

Update Metadata

Replaces the metadata for the requested token and refreshes the OpenSea cache.

Request

PATCH /phygitals/metadata

Headers

Header	Value	Required
`content-type`	`application/json`	Yes
`x-iyk-api-key`	API key for user	Yes

Request Body

Field	Description	Type
`contractAddress`	Contract address of the token	`string`
`chainId`	Chain ID of the network where the token resides	`number`
`tokenId`	ID of the token	`string`
`metadata`	JSON string for the updated metadata	`string`

Metadata JSON Format

Refer to OpenSea's metadata structure (opens in a new tab) for more information. Any additional fields will be preserved and added to the token metadata.

Required strings can be empty strings, and required arrays can be empty arrays.

Field	Description	Type	Required
`name`	Token name	`string`	Yes
`collection`	Collection name (subheading of the tap screen)	`string`	Yes
`description`	Token description	`string`	Yes
`image`	URL for token image	`string`	Yes
`attributes`	JSON string of updated metadata	`{ trait_type: string, value: string \| number, display_type?: string }[]`	Yes
`media_gallery`	JSON string of updated metadata	`{ media: <URL string>, type: <MIME type string> }[]`	Yes

Example Request Body

{
  "chainId": 137,
  "contractAddress": "0x17827126bda4a649b578191ff17275fdd6a20167",
  "tokenId": "3",
  "metadata": "{\"name\":\"MacDaddy Beanie #3\",\"description\":\"Swaggggy beanie for mac and cheeasy\",\"image\":\"https://files.iyk.app/beanie.png\",\"attributes\":[{\"trait_type\":\"Item Type\",\"value\":\"Beanie\"},{\"trait_type\":\"Size\",\"value\":\"M\"}],\"collection\":\"MacDaddy TEST METADATA UPDATE\",\"media_gallery\":[{\"media\":\"https://files.iyk.app/gallery-1.png\",\"type\":\"image/png\"},{\"media\":\"https://files.iyk.app/gallery-2.jpg\",\"type\":\"image/jpeg\"}],\"customField\":\"TEST 2\"}"
}

Response

{
  "success": true
}

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`

Error Response

{
  "success": false,
  "errors": {
    "metadata.image": "Required"
  }
}

OTP Codes POAP Events