Guestbook Events

Guestbook Events are ERC1155 tokens that represent attendance at a specific event, or an interaction with a physical product.

Deploy a Guestbook Contract

Creates a new guestbook contract.

Request

POST /events/contracts

Headers

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

Body

Field	Description	Type
`name`	Name for the contract	`string`
`symbol`	Symbol for the contract	`string`
`chainId`	The chain ID where the contract is deployed	`number`

Response

{
  "success": true,
  "contractId": 123
}

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`contractId`	The unique identifier of the created contract	`number`

Get Guestbook Contracts for a Team

Retrieves all guestbook contracts associated with a team.

Request

GET /events/contracts

Headers

Header	Value	Required
`x-iyk-api-key`	API key for user	Yes

Response

Returns an array of contract objects.

Field	Description	Type
`id`	Unique identifier of the contract	`number`
`name`	Name of the contract	`string`
`symbol`	Symbol of the contract	`string`
`address`	Contract address	`string \| null`
`chainId`	Contract chain ID	`number`
`createdAt`	Contract creation timestamp	`string`
`status`	Deployment status of the contract	`"pending" \| "confirmed"`

Example Response

[
    {
        "id": 123,
        "name": "TEST",
        "symbol": "TEST",
        "address": null,
        "chainId": 137,
        "createdAt": "2024-02-07T21:39:01.012Z",
        "status": "pending"
    },
    ...
]

Metadata Structure for Guestbook Events

The below structure is used to define the metadata when creating or updating a guestbook event's associated token. All fields are based on the OpenSea Metadata Standard (opens in a new tab).

Metadata Fields

Field	Description	Type	Required
`name`	The name of the event	`string`	Yes
`collection`	The collection to which the event belongs	`string`	Yes
`description`	The description of the event	`string`	Yes
`image`	URL pointing to an image associated with the event	`string`	Yes
`attributes`	List of attributes for the event	`Array<Attribute>`	Yes

Attribute Object Structure

Each attribute within the attributes array should follow this structure:

Field	Description	Type	Required
`trait_type`	The name of the attribute	`string`	Yes
`value`	The value of the attribute	`string` \| `number`	Yes
`display_type`	The display type of the attribute (optional, refer to OpenSea standard)	`string?`	No

Example Metadata JSON

An example of how to format the metadata JSON string for a guestbook event:

{
  "name": "Conference 2024",
  "collection": "Conferences",
  "description": "A gathering of professionals to discuss industry trends.",
  "image": "https://example.com/image.png",
  "attributes": [
    {
      "trait_type": "Location",
      "value": "New York"
    },
    {
      "trait_type": "Date",
      "value": "2024-05-20"
    },
    {
      "trait_type": "Attendees",
      "value": 500,
      "display_type": "number"
    }
  ]
}

Create a Guestbook Event

Creates a new guestbook event for a specified guestbook contract.

Request

POST /events

Headers

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

Body

Field	Description	Type
`name`	Private label for the event	`string`
`tokenId`	Token ID associated with the event	`string`
`contractId`	ID of the guestbook contract	`string`
`metadata`	JSON string containing the token metadata (refer to metadata structure)	`string`

Example Body

{
  "name": "TEST Event 3",
  "tokenId": "3",
  "contractId": 121,
  "metadata": "{\"name\":\"AnnualConference\",\"collection\":\"Conferences\",\"description\":\"Agatheringofprofessionalstodiscussindustrytrends.\",\"image\":\"https://example.com/image.png\",\"iyk_metadata_version\":\"1.0\",\"attributes\":[{\"trait_type\":\"Location\",\"value\":\"NewYork\"},{\"trait_type\":\"Date\",\"value\":\"2024-05-20\"},{\"trait_type\":\"Attendees\",\"value\":500,\"display_type\":\"number\"}]}"
}

Response

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`id`	The unique identifier of the created event	`number`

Example Response

{
  "success": true,
  "id": 123
}

Get Guestbook Events for a Team

Retrieves all guestbook events associated with the user's team.

Request

GET /events

Headers

Header	Value	Required
`x-iyk-api-key`	API key for user	Yes

Query Parameters

Field	Type	Description	Required
`contractId`	`number`	The contract ID to filter for	No*

Response

Returns an array of event objects, including details and contract information.

Field	Description	Type
`id`	Unique identifier of the event	`number`
`name`	Name of the event	`string`
`contract`	Object containing contract details	`object`
`contract.id`	ID of the associated contract	`number`
`contract.address`	Contract address	`string`
`contract.chainId`	Blockchain chain ID	`number`
`contract.tokenId`	Token ID associated with the event	`string`
`createdAt`	Creation timestamp	`string`

Example Response

[
    {
        "id": 92,
        "name": "TEST Event 1",
        "contract": {
            "id": 121,
            "contractAddress": "0x8a7eacf921a11c078ca9e873921da3bcdedf6e70",
            "chainId": 137,
            "tokenId": "1"
        },
        "createdAt": "2024-02-08T03:55:32.372Z"
    }
    ...
]

Update Metadata for a Guestbook Event

Updates the metadata for a specified guestbook event.

Request

PATCH /events/metadata

Headers

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

Body

Field	Description	Type
`eventId`	(Optional) ID of the event to update	`string`
`tokenId`	Token ID, required if eventId is not provided	`string`
`contractAddress`	Contract address, required if eventId is not provided	`string`
`chainId`	Chain ID, required if eventId is not provided	`number`
`metadata`	JSON string containing the new metadata (refer to metadata structure)	`string`

Example Body

{
  "contractId": 121,
  "tokenId": "1",
  "name": "TEST Event 1",
  "metadata": "{\"name\":\"DEV CHIP #1\",\"description\":\"For development purposes.\",\"image\":\"https://files.iyk.app/products/18e8e5f3-ee04-4170-a7ea-afb943369a10/iyk_black_shirt.mp4\",\"attributes\":[{\"trait_type\":\"Purpose\",\"value\":\"Development\"}],\"collection\":\"DEV\",\"media_gallery\":[]}"
}

Response

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

Example Response

{
  "success": true
}

Mint for a Guestbook Event

Mints a token for a specified guestbook event.

Request

POST /events/mint

Headers

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

Body

Field	Description	Type
`eventId`	(Optional) ID of the event to mint for	`string`
`tokenId`	Token ID, required if eventId is not provided	`string`
`contractAddress`	Contract address, required if eventId is not provided	`string`
`chainId`	Chain ID, required if eventId is not provided	`number`
`recipient`	Address of the recipient	`string`

Response

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`txnHash`	Transaction hash of the mint operation	`string`

Example Response

{
  "success": true,
  "txnHash": "transaction_hash"
}

I'll add the documentation for the new mint/self function.

Mint for a Guestbook Event (Self)

Mints a token for a specified guestbook event using the claim code.

Request

POST /events/mint/self

Headers

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

Body

Field	Description	Type
`recipient`	ETH address or ENS name of the recipient	`string`

Example Body

{
  "recipient": "0xRecipientAddressOrENSName"
}

Response

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`txnHash`	Transaction hash of the mint operation	`string`

Example Response

{
  "success": true,
  "txnHash": "transaction_hash"
}

Assign Guestbook Event to Tag (Legacy)

Assigns a guestbook event to specified tags.

Request

POST /events/assign/legacy

Headers

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

Body

Field	Description	Type
`tagUIDs`	List of tag UIDs to assign the event	`string[]`
`guestbookEventId`	ID of the guestbook event to assign	`number`

Example Body

{
  "tagUIDs": ["tagUID1", "tagUID2"],
  "guestbookEventId": 123
}

Response

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

Example Response

{
  "success": true
}

Certainly! I'll add the documentation for the POST /toggle-pause-state endpoint to your existing documentation. Here's the new section to be added:

Toggle Transfer Pause State for a Guestbook Contract

Toggles the pause state for transfers on a specified guestbook contract. If pauseState is true, transfers will be paused (soulbound).

Request

POST /events/toggle-pause-state

Headers

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

Body

Field	Description	Type
`contractId`	ID of the guestbook contract (optional if address is provided)	`number`
`contractAddress`	Address of the guestbook contract (optional if ID is provided)	`string`
`chainId`	Chain ID of the contract (required if address is provided)	`number`
`pauseState`	The desired pause state (true to pause, false to unpause)	`boolean`

Note: Either contractId or both contractAddress and chainId must be provided.

Example Body

{
  "contractId": 123,
  "pauseState": true
}

Response

Field	Description	Type
`success`	Indicates if the request was successful	`boolean`
`txnHash`	Transaction hash of the toggle pause state action	`string`

Example Response

{
  "success": true,
  "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

POAP Events Self-Service POAP Devices