Kairos API

A simple GraphQL API for the Kairos platform, to programatically create, mint, and sell NFTs. To complement this documentation:

When using beta, blockchain operations are free. They use the valueless testnet blockchains Görli (Ethereum) and Mumbai (Polygon). When interacting with testnets, switch your wallets’ network one of these networks.

Feel free to ping us to chat ask questions over Slack Connect or Discord :) We're happy to help you figure out your implementation.

API Endpoints
# Beta:
https://beta.kairos.art/public/graphql
# Production:
https://kairos.art/public/graphql
Headers
Authorization: Basic <BASE_64_ENCODING_OF_API_KEY>

Authorisation

You'll provide an API key in the Authorization header, which you can get from Kairos. Encode the API in base 64, and prefix it with Basic . An example in Javascript is:

  `Basic ${Buffer.from(KAIROS_API_KEY).toString('base64')}`

New to GraphQL

There’s no need for custom libraries or anything complex (unless you’re feeling daring). You can make standard XHR requests with libraries like axios or Node’s fetch. For example:

  const res = await axios.post(KAIROS_API_URL,
    {
      query: `
        # The signature that describes the action to do
        # and variables it needs
        query nft($nftId: UUID!) {
          nft(nftId: $nftId) {
            # The fields you want to get back.
            # You can pick just the fields that you need.
            id
            name
          }
        }
      `,
      variables: {
        // The variables that were defined in the signature
        nftId: '...'
      },
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': '...'
      }
    }
  );

Queries

collectorOwnershipsByCollection

Description

Gets the known relationship between a user's wallet and an NFT. Ownerships may be delayed when NFTs are transferred or resold.

Response

Returns [Ownership]!

Arguments
Name Description
collectionId - UUID!
sessionToken - String! The JWT, or value from the user's cookie

Example

Query
query collectorOwnershipsByCollection(
  $collectionId: UUID!,
  $sessionToken: String!
) {
  collectorOwnershipsByCollection(
    collectionId: $collectionId,
    sessionToken: $sessionToken
  ) {
    id
    nftId
    nft {
      id
      name
      description
      collectionId
      mintPubkey
      metadataPatch {
        description
        external_url
        image
        attributes {
          trait_type
          value
        }
      }
    }
  }
}
Variables
{
  "collectionId": "W3Y1fkg5eutfSGXpFSq",
  "sessionToken": "eyJhbGci0iJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi0iIxMiMONTY30DkwIiwibmFtZSI6IkpvaG4gRG91IiwiaXNTb2NpYWwi0nRydWV9.4pcPMD0901PSyXnrXCiTwXyr4BsezdI1AVTmud2fU4"
}
Response
{
  "data": {
    "collectorOwnershipsByCollection": [
      {
        "id": "W3Y1fkg5eutfSGXpFSq",
        "nftId": "W3Y1fkg5eutfSGXpFSq",
        "nft": Nft
      }
    ]
  }
}

nft

Response

Returns a Nft!

Arguments
Name Description
nftId - UUID!

Example

Query
query nft($nftId: UUID!) {
  nft(nftId: $nftId) {
    id
    name
    description
    collectionId
    mintPubkey
    metadataPatch {
      description
      external_url
      image
      attributes {
        trait_type
        value
      }
    }
  }
}
Variables
{"nftId": "W3Y1fkg5eutfSGXpFSq"}
Response
{
  "data": {
    "nft": {
      "id": "W3Y1fkg5eutfSGXpFSq",
      "name": "Bonsai Billy",
      "description": "Your bonsai tree lives it in your wallet but it needs to be cared for. Care for it at https://bonsaiwallet.com",
      "collectionId": "W3Y1fkg5eutfSGXpFSq",
      "mintPubkey": "0xb794f5ea0ba39494ce839613fffba74279579268",
      "metadataPatch": MetadataPatch
    }
  }
}

session

Description

Gets the session for the user's current session token that is stored in the cookie

Response

Returns a Session

Arguments
Name Description
sessionToken - String! The JWT, or value from the user's cookie

Example

Query
query session($sessionToken: String!) {
  session(sessionToken: $sessionToken) {
    id
    userId
    walletId
    userAgent
    ipAddress
    expiresAt
    createdAt
    user {
      id
      email
    }
    wallet {
      id
      pubkey
      isCustody
    }
  }
}
Variables
{
  "sessionToken": "eyJhbGci0iJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi0iIxMiMONTY30DkwIiwibmFtZSI6IkpvaG4gRG91IiwiaXNTb2NpYWwi0nRydWV9.4pcPMD0901PSyXnrXCiTwXyr4BsezdI1AVTmud2fU4"
}
Response
{
  "data": {
    "session": {
      "id": "W3Y1fkg5eutfSGXpFSq",
      "userId": "W3Y1fkg5eutfSGXpFSq",
      "walletId": "W3Y1fkg5eutfSGXpFSq",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36",
      "ipAddress": "123.123.123.123",
      "expiresAt": "2023-10-07T01:08:03.420Z",
      "createdAt": "2023-10-07T01:08:03.420Z",
      "user": User,
      "wallet": Wallet
    }
  }
}

userByNftId

Description

Gets the user that owns the NFT with the given ID.

Response

Returns a User!

Arguments
Name Description
nftId - UUID!

Example

Query
query userByNftId($nftId: UUID!) {
  userByNftId(nftId: $nftId) {
    id
    email
  }
}
Variables
{"nftId": "W3Y1fkg5eutfSGXpFSq"}
Response
{
  "data": {
    "userByNftId": {
      "id": "W3Y1fkg5eutfSGXpFSq",
      "email": "billy@example.com"
    }
  }
}

Mutations

createOneOfOneNft

Description

Creates a new NFT in the collection on Kairos. This does not deploy the NFT to the blockchain.

Response

Returns a CreateOneOfOneNft!

Arguments
Name Description
input - CreateOneOfOneNftInput!

Example

Query
mutation createOneOfOneNft($input: CreateOneOfOneNftInput!) {
  createOneOfOneNft(input: $input) {
    ... on CreateNftRes {
      nft {
        id
        name
        description
        collectionId
        mintPubkey
        metadataPatch {
          description
          external_url
          image
          attributes {
            trait_type
            value
          }
        }
      }
    }
    ... on CreateOneOfOneNftError {
      message
    }
  }
}
Variables
{"input": CreateOneOfOneNftInput}
Response
{"data": {"createOneOfOneNft": CreateNftRes}}

deployNft

Description

Deploys the collection to the blockchain (if it hasn't been deployed yet) and then, depending on the type of NFT, deploys some or all of the metadata of the NFT to the blockchain. This can only be done once per NFT. NFTs are "lazy minted" to the blockchain, meaning that their metadata is put on-chain in this operation but the NFT itself doesn't exist, and isn't assigned to any wallet until purchase.

Response

Returns a Nft!

Arguments
Name Description
input - DeployNftInput!

Example

Query
mutation deployNft($input: DeployNftInput!) {
  deployNft(input: $input) {
    id
    name
    description
    collectionId
    mintPubkey
    metadataPatch {
      description
      external_url
      image
      attributes {
        trait_type
        value
      }
    }
  }
}
Variables
{"input": DeployNftInput}
Response
{
  "data": {
    "deployNft": {
      "id": "W3Y1fkg5eutfSGXpFSq",
      "name": "Bonsai Billy",
      "description": "Your bonsai tree lives it in your wallet but it needs to be cared for. Care for it at https://bonsaiwallet.com",
      "collectionId": "W3Y1fkg5eutfSGXpFSq",
      "mintPubkey": "0xb794f5ea0ba39494ce839613fffba74279579268",
      "metadataPatch": MetadataPatch
    }
  }
}

updateDynamicMetadata

Description

Updates the metadata for the NFT. You can change the metadata after deploy and after purchase. Requires the collection to have hasDynamicMetadata set to true.

Response

Returns a Boolean!

Arguments
Name Description
input - UpdateDynamicMetadataInput!

Example

Query
mutation updateDynamicMetadata($input: UpdateDynamicMetadataInput!) {
  updateDynamicMetadata(input: $input)
}
Variables
{"input": UpdateDynamicMetadataInput}
Response
{"data": {"updateDynamicMetadata": false}}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example
true

CreateNftRes

Fields
Field Name Description
nft - Nft!
Example
{"nft": Nft}

CreateOneOfOneNft

Example
CreateNftRes

CreateOneOfOneNftError

Fields
Field Name Description
message - CreateOneOfOneNftErrorCode!
Example
{"message": "MAX_NFTS"}

CreateOneOfOneNftErrorCode

Values
Enum Value Description

MAX_NFTS

GENERATIVE

Example
"MAX_NFTS"

CreateOneOfOneNftInput

Fields
Input Field Description
collectionId - UUID!
name - String!
description - String! The description that appears in the user's wallet below the NFT name, and in marketplaces. You can use Markdown here.
price - Float! The price in native cryptocurrency set for the collection. E.g. a collection on the Ethereum blockchain will have a price in ETH; a collection on the Polygon blockchain will have a price in MATIC.
Example
{
  "collectionId": "W3Y1fkg5eutfSGXpFSq",
  "name": "Bonsai Billy",
  "description": "Your bonsai tree lives it in your wallet but it needs to be cared for. Care for it at https://bonsaiwallet.com",
  "price": 987.65
}

Date

Description

DateTime

Example
"2023-10-07T01:08:03.420Z"

DeployNftInput

Fields
Input Field Description
nftId - UUID!
isBlocking - Boolean When true, the request will not return success until the NFT has been deployed to the blockchain.
Example
{
  "nftId": "W3Y1fkg5eutfSGXpFSq",
  "isBlocking": true
}

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65

MetadataAttribute

Fields
Field Name Description
trait_type - String!
value - MetadataTraitValue!
Example
{
  "trait_type": "abc123",
  "value": MetadataTraitValue
}

MetadataAttributeInput

Fields
Input Field Description
trait_type - String!
value - MetadataTraitValue!
Example
{
  "trait_type": "xyz789",
  "value": MetadataTraitValue
}

MetadataPatch

Fields
Field Name Description
description - String The description that appears in the user's wallet below the NFT name, and in marketplaces. You can use Markdown here.
external_url - URI A link out to a relevant website. Some wallets and marketplaces may not support this field, so if this is call-to-action, also include it in the description.
image - URI The original, high-res image of the NFT. If this image is ephemeral or will change over time, feel free to upload it to something simple and cheap like S3. When the image will be static, it's more web3-conventional to upload it to a permanent storage solution like Arweave.
attributes - [MetadataAttribute] Web3-standardized attributes for the NFT. This determines the uniquenesses, rarity, and resale value. Conventionally, these are assigned randomly at purchase, or through user effort (e.g. staking, gameplay, interaction.) For more information, see: https://docs.opensea.io/docs/metadata-standards#attributes
Example
{
  "description": "xyz789",
  "external_url": "https://www.example.com/image.png",
  "image": "https://www.example.com/image.png",
  "attributes": [MetadataAttribute]
}

MetadataPatchInput

Fields
Input Field Description
description - String The description that appears in the user's wallet below the NFT name, and in marketplaces. You can use Markdown here.
external_url - URI A link out to a relevant website. Some wallets and marketplaces may not support this field, so if this is call-to-action, also include it in the description.
image - URI The original, high-res image of the NFT. If this image is ephemeral or will change over time, feel free to upload it to something simple and cheap like S3. When the image will be static, it's more web3-conventional to upload it to a permanent storage solution like Arweave.
attributes - [MetadataAttributeInput] Web3-standardized attributes for the NFT. This determines the uniquenesses, rarity, and resale value. Conventionally, these are assigned randomly at purchase, or through user effort (e.g. staking, gameplay, interaction.) For more information, see: https://docs.opensea.io/docs/metadata-standards#attributes
Example
{
  "description": "Your bonsai tree lives it in your wallet but it needs to be cared for. Care for it at https://bonsaiwallet.com",
  "external_url": "https://bonsaiwallet.com",
  "image": "https://bonsai.s3.amazonaws.com/1234.png",
  "attributes": [MetadataAttributeInput]
}

MetadataTraitValue

Description

A string or number following OpenSea metadata standards

Example
MetadataTraitValue

Nft

Fields
Field Name Description
id - UUID
name - String
description - String
collectionId - UUID
mintPubkey - PubkeyBase58 " The on-chain unique identifier of the NFT in the collection. Also known as tokenId (uint256). Usually (but not always) an incrementing integer by order of minting.
metadataPatch - MetadataPatch
Example
{
  "id": "W3Y1fkg5eutfSGXpFSq",
  "name": "Bonsai Billy",
  "description": "Your bonsai tree lives it in your wallet but it needs to be cared for. Care for it at https://bonsaiwallet.com",
  "collectionId": "W3Y1fkg5eutfSGXpFSq",
  "mintPubkey": "0xb794f5ea0ba39494ce839613fffba74279579268",
  "metadataPatch": MetadataPatch
}

Ownership

Description

An ownership connects minted NFTs to wallets. A user can have many wallets.

Fields
Field Name Description
id - UUID!
nftId - UUID!
nft - Nft
Example
{
  "id": "W3Y1fkg5eutfSGXpFSq",
  "nftId": "W3Y1fkg5eutfSGXpFSq",
  "nft": Nft
}

PubkeyBase58

Description

The wallet's public key, or address

Example
"0xb794f5ea0ba39494ce839613fffba74279579268"

Session

Fields
Field Name Description
id - UUID
userId - UUID
walletId - UUID
userAgent - String
ipAddress - String
expiresAt - Date When a session is expiring or has been manually expired
createdAt - Date
user - User
wallet - Wallet
Example
{
  "id": "W3Y1fkg5eutfSGXpFSq",
  "userId": "W3Y1fkg5eutfSGXpFSq",
  "walletId": "W3Y1fkg5eutfSGXpFSq",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36",
  "ipAddress": "123.123.123.123",
  "expiresAt": "2023-10-07T01:08:03.420Z",
  "createdAt": "2023-10-07T01:08:03.420Z",
  "user": User,
  "wallet": Wallet
}

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"abc123"

URI

Example
"https://www.example.com/image.png"

UUID

Example
"W3Y1fkg5eutfSGXpFSq"

UpdateDynamicMetadataInput

Fields
Input Field Description
nftId - UUID!
metadataPatch - MetadataPatchInput!

Overrides to the metadata for the NFT. Any fields not provided are defaulted to values computed from the Collection or the initial NFT creation.

Providing an array value for an attribute will replace the default array value. To remove an attribute previously set, omit it from the next request.

Example
{
  "nftId": "W3Y1fkg5eutfSGXpFSq",
  "metadataPatch": MetadataPatchInput
}

User

Fields
Field Name Description
id - UUID
email - String!
Example
{
  "id": "W3Y1fkg5eutfSGXpFSq",
  "email": "billy@example.com"
}

Wallet

Fields
Field Name Description
id - UUID
pubkey - PubkeyBase58! Either their own custody or ours
isCustody - Boolean A wallet in our custody
Example
{
  "id": "W3Y1fkg5eutfSGXpFSq",
  "pubkey": "0xb794f5ea0ba39494ce839613fffba74279579268",
  "isCustody": true
}