nft-apps-openrpc.json

{
    "openrpc": "1.2.4",
    "info": {
        "title": "StarkEx NFT Application API",
        "description": "A specification of a standard interface for NFT applications using StarkEx",
        "version": "0.2.0"
    },
    "methods": [
        {
            "name": "starkex_getUserAssets",
            "description": "Retrieve a user's known assets",
            "params": [
                {
                    "name": "stark_key",
                    "description": "The stark key identifying the user",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/STARK_KEY"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": false,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "assets": {
                            "description": "The assets for this user",
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/ASSET"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    }
                }
            }
        },
        {
            "name": "starkex_getAssetInfo",
            "description": "Given an asset id retrieve all the asset information",
            "params": [
                {
                    "name": "asset_id",
                    "description": "The asset's id",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/ASSET_ID"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "$ref": "#/components/schemas/ASSET"
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/ASSET_NOT_FOUND"
                }
            ]
        },
        {
            "name": "starkex_getAssetsByFilter",
            "description": "Retrieve all assets that adhere to the given filter",
            "params": [
                {
                    "name": "filter",
                    "description": "The filter used to choose the assets to return",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/ASSET_FILTER"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "assets": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/ASSET_WITH_TXN_HISTORY"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    },
                    "required": [
                        "assets"
                    ]
                }
            }
        },
        {
            "name": "starkex_createCollection",
            "description": "Create a collection with the necessary info",
            "params": [
                {
                    "name": "collection_info",
                    "description": "The new collection information",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/NFT_COLLECTION_INFO"
                    }
                }
            ],
            "result": {
                "name": "collection_id",
                "description": "The newly created collection id",
                "schema": {
                    "$ref": "#/components/schemas/COLLECTION_ID"
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/INVALID_COLLECTION_INFO"
                }
            ]
        },
        {
            "name": "starkex_getCollectionInfo",
            "description": "Given a collection id, retrieve the collection information",
            "params": [
                {
                    "name": "collection_id",
                    "description": "The requested collection id",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/COLLECTION_ID"
                    }
                }
            ],
            "result": {
                "name": "result",
                "description": "The requested collection information",
                "schema": {
                    "$ref": "#/components/schemas/NFT_COLLECTION_INFO"
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/COLLECTION_NOT_FOUND"
                }
            ]
        },
        {
            "name": "starkex_getCollectionContent",
            "description": "Given a collection id, retrieve assets in the collection",
            "params": [
                {
                    "name": "collection_id",
                    "description": "The requested collection id",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/COLLECTION_ID"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "assets": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/ASSET"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    },
                    "required": [
                        "assets"
                    ]
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/COLLECTION_NOT_FOUND"
                }
            ]
        },
        {
            "name": "starkex_getCollectionsByFilter",
            "description": "Given a filter, return all collection info that matches the filter",
            "params": [
                {
                    "name": "filter",
                    "description": "The filter used to choose the collections to return",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/FILTER"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "collections": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/NFT_COLLECTION_INFO"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    },
                    "required": [
                        "collections"
                    ]
                }
            }
        },
        {
            "name": "starkex_submitOrder",
            "description": "Submit an order to buy or sell an NFT",
            "params": [
                {
                    "name": "order",
                    "description": "The submitted order",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/ORDER"
                    }
                }
            ],
            "result": {
                "name": "order_id",
                "schema": {
                    "$ref": "#/components/schemas/ORDER_ID"
                }
            }
        },
        {
            "name": "starkex_cancelOrder",
            "description": "Cancel an order that was already submitted",
            "params": [
                {
                    "name": "order_id",
                    "description": "The id of the order to cancel",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/ORDER_ID"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": true
            },
            "errors": [
                {
                    "$ref": "#/components/errors/ORDER_NOT_FOUND"
                }
            ]
        },
        {
            "name": "starkex_getOpenOrdersByFilter",
            "description": "Get all the open orders that match the given filter",
            "params": [
                {
                    "name": "filter",
                    "description": "The filter used to choose the orders",
                    "required": true,
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/KEYWORD"
                        }
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "orders": {
                            "type": "array",
                            "description": "All the open orders for assets that have one of the input keywords, or belong to a collection that has one of these keywords",
                            "items": {
                                "$ref": "#/components/schemas/ORDER_WITH_ID"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    },
                    "required": [
                        "orders"
                    ]
                }
            }
        },
        {
            "name": "starkex_getUserHistory",
            "description": "For a given user, get the order history for that user",
            "params": [
                {
                    "name": "stark_key",
                    "description": "The stark key identifying the user",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/STARK_KEY"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "items": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/USER_HISTORY_ITEM"
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    },
                    "required": [
                        "items"
                    ]
                }
            }
        },
        {
            "name": "starkex_submitSettlement",
            "description": "Submit 2 orders (buy+sell) to be settled",
            "params": [
                {
                    "name": "settlement",
                    "required": true,
                    "description": "The settlement to add",
                    "schema": {
                        "$ref": "#/components/schemas/SETTLEMENT"
                    }
                }
            ],
            "result": {
                "name": "transaction_id",
                "description": "The transaction id of the created settlement transaction. This is the starkex transaction id.",
                "schema": {
                    "$ref": "#/components/schemas/TXN_ID"
                }
            }
        },
        {
            "name": "starkex_mint",
            "description": "Mint a number of NFTs",
            "params": [
                {
                    "name": "mint_info",
                    "description": "The information for the mint operation",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/MINT_OPERATION_INFO"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "transaction_id": {
                            "$ref": "#/components/schemas/TXN_ID"
                        },
                        "vault_id": {
                            "$ref": "#/components/schemas/VAULT_ID"
                        },
                        "asset_type": {
                            "$ref": "#/components/schemas/ASSET_TYPE"
                        },
                        "minting_blob": {
                            "$ref": "#/components/schemas/MINTING_BLOB"
                        },
                        "asset_id": {
                            "$ref": "#/components/schemas/ASSET_ID"
                        }
                    }
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/INVALID_MINT_INPUT"
                }
            ]
        },
        {
            "name": "starkext_getMintStatus",
            "description": "Get the status of a mint transaction",
            "params": [
                {
                    "name": "transaction_id",
                    "description": "The id of the sent mint transaction",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/TXN_ID"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "$ref": "#/components/schemas/TXN_STATUS"
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/TRANSACTION_NOT_FOUND"
                }
            ]
        },
        {
            "name": "starkex_getMintHistoryForUser",
            "description": "For the given user key, retrieve the mint operations where it is the owner",
            "params": [
                {
                    "name": "owner_key",
                    "required": true,
                    "description": "The stark key of the owner for the minted NFTs (for which they were minted)",
                    "schema": {
                        "$ref": "#/components/schemas/STARK_KEY"
                    }
                },
                {
                    "name": "page_request",
                    "description": "The information required to return a specific page of results",
                    "required": true,
                    "schema": {
                        "$ref": "#/components/schemas/RESULT_PAGE_REQUEST"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "object",
                    "properties": {
                        "mint_ops": {
                            "type": "array",
                            "items": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/MINT_OPERATION_INFO"
                                    },
                                    {
                                        "type": "object",
                                        "properties": {
                                            "transaction_id": {
                                                "$ref": "#/components/schemas/TXN_ID"
                                            },
                                            "status": {
                                                "$ref": "#/components/schemas/TXN_STATUS"
                                            }
                                        }
                                    }
                                ]
                            }
                        },
                        "continuation_token": {
                            "description": "A pointer to the last element of the delivered page, can be used to sent with subsequent queries to more pages",
                            "type": "string"
                        }
                    }
                }
            }
        },
        {
            "name": "starkex_subscribe",
            "description": "Subscribe to a stream of events",
            "params": [
                {
                    "name": "requested_transaction_types",
                    "required": false,
                    "description": "The events the client wishes to listen to",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/TXN_TYPE"
                        }
                    }
                },
                {
                    "name": "requested_statuses",
                    "required": false,
                    "description": "The transaction statuses the client would like to listen to",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PROCESSING_STATUS"
                        }
                    }
                },
                {
                    "name": "start_from",
                    "required": false,
                    "description": "The earliest timestamp for events to retrieve on the stream. A UTC timestamp, default to now.",
                    "schema": {
                        "$ref": "#/components/schemas/TIMESTAMP"
                    }
                }
            ],
            "result": {
                "name": "result",
                "description": "The subscription id",
                "schema": {
                    "type": "string"
                }
            },
            "errors": [
                {
                    "$ref": "#/components/errors/SUBSCRIPTION_UNSUCCESSFUL"
                }
            ]
        },
        {
            "name": "starkex_unsubscribe",
            "description": "Unsubscribe from a given event stream",
            "params": [
                {
                    "name": "subscription_id",
                    "description": "The subscription id, as returned from the subscribe method",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "result": {
                "name": "result",
                "schema": {
                    "type": "boolean",
                    "description": "Returns true if the subscription was cancelled successfully"
                }
            }
        }
    ],
    "components": {
        "schemas": {
            "TXN_TYPE": {
                "anyOf": [
                    {
                        "type": "string",
                        "enum": [
                            "TRANSFER",
                            "SETTLEMENT",
                            "MINT",
                            "DEPOSIT",
                            "WITHDRAW",
                            "COND_TRANSFER",
                            "FULL_WITHDRAWAL"
                        ]
                    },
                    {
                        "$comment": "Allow future transaction types to be added and pass validation",
                        "type": "string"
                    }
                ]
            },
            "PROCESSING_STATUS": {
                "type": "string",
                "enum": [
                    "RECEIVED",
                    "PROCESSING",
                    "ACCEPTED",
                    "REJECTED"
                ]
            },
            "DEPOSIT_OR_WITHDRAW": {
                "type": "object",
                "properties": {
                    "txn_type": {
                        "type": "string",
                        "$comment": "accepted values are DEPOSIT/WITHDRAW, like in TXN_TYPE. It's in the event, but also here so the object is self-contained",
                        "enum": [
                            "DEPOSIT",
                            "WITHDRAW"
                        ]
                    },
                    "vault_id": {
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "stark_key": {
                        "description": "Public key of the party as registered on the StarkEx contract",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "token_id": {
                        "$ref": "#/components/schemas/ASSET_TYPE"
                    },
                    "amount": {
                        "description": "Amount of token to be deposited",
                        "type": "integer",
                        "minimum": 0
                    },
                    "transaction_id": {
                        "$ref": "#/components/schemas/TXN_ID"
                    }
                }
            },
            "COND_TRANSFER": {
                "description": "A conditional transfer transaction",
                "type": "object",
                "properties": {
                    "amount": {
                        "description": "Amount transferred",
                        "type": "integer",
                        "minimum": 0
                    },
                    "nonce": {
                        "description": "The nonce used when signing the transaction",
                        "$ref": "#/components/schemas/NONCE"
                    },
                    "sender_public_key": {
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "sender_vault_id": {
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "token": {
                        "$ref": "#/components/schemas/TOKEN_ID"
                    },
                    "receiver_public_key": {
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "receiver_vault_id": {
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "fact_registry_address": {
                        "description": "The address of the fact registry smart contract",
                        "$ref": "#/components/schemas/ETH_ADDRESS"
                    },
                    "fact": {
                        "description": "The fact that should appear in the fact registry as a condition to the transfer",
                        "$comment": "A 32 byte blob, as 64 hex digits",
                        "type": "string",
                        "pattern": "^0x[a-fA-F0-9]{64}$"
                    },
                    "expiration_timestamp": {
                        "description": "The expiration timestamp of the transaction",
                        "$ref": "#/components/schemas/EXPIRATION_TIMESTAMP"
                    },
                    "transaction_id": {
                        "$ref": "#/components/schemas/TXN_ID"
                    }
                }
            },
            "FULL_WITHDRAWAL": {
                "type": "object",
                "properties": {
                    "vault_id": {
                        "description": "The vault ID in StarkEx to withdraw from",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "stark_key": {
                        "description": "The key of the user withdrawing, as registered on the StarkEx contract",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "is_false": {
                        "description": "A flag indicating whether this is a false full withdrawal",
                        "type": "boolean"
                    }
                }
            },
            "MULTI_TRANSACTION": {
                "type": "object",
                "properties": {
                    "txs": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/SINGLE_TRANSACTION"
                        }
                    }
                }
            },
            "SINGLE_TRANSACTION": {
                "$comment": "Future transaction types should extend one of these below, with additional properties allowed. The transaction type should indicate the semantic of the object and how the client should parse it",
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/TRANSFER_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/SETTLEMENT_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/MINT_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/DEPOSIT_OR_WITHDRAW"
                    },
                    {
                        "$ref": "#/components/schemas/COND_TRANSFER"
                    },
                    {
                        "$ref": "#/components/schemas/FULL_WITHDRAWAL"
                    }
                ]
            },
            "STARKEX_EVENT": {
                "type": "object",
                "properties": {
                    "time": {
                        "description": "A UTC timestamp for when the event occurred in StarkEx",
                        "$ref": "#/components/schemas/TIMESTAMP"
                    },
                    "transaction_type": {
                        "$ref": "#/components/schemas/TXN_TYPE"
                    },
                    "status": {
                        "$ref": "#/components/schemas/PROCESSING_STATUS"
                    },
                    "transaction": {
                        "anyOf": [
                            {
                                "$ref": "#/components/schemas/SINGLE_TRANSACTION"
                            },
                            {
                                "$ref": "#/components/schemas/MULTI_TRANSACTION"
                            }
                        ]
                    }
                },
                "required": [
                    "transaction_type"
                ]
            },
            "ASSET_HISTORY_ITEM": {
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/MINT_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/SETTLEMENT_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/TRANSFER_WITH_ID"
                    }
                ]
            },
            "USER_HISTORY_ITEM": {
                "oneOf": [
                    {
                        "type": "object",
                        "properties": {
                            "order": {
                                "$ref": "#/components/schemas/ORDER_WITH_ID"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "OPEN",
                                    "CLOSED",
                                    "EXPIRED",
                                    "SETTLED",
                                    "CANCELLED"
                                ]
                            }
                        }
                    },
                    {
                        "$ref": "#/components/schemas/SETTLEMENT_WITH_ID"
                    },
                    {
                        "$ref": "#/components/schemas/TRANSFER"
                    }
                ]
            },
            "TRANSFER": {
                "type": "object",
                "properties": {
                    "amount": {
                        "description": "Amount transferred",
                        "type": "integer",
                        "minimum": 0
                    },
                    "nonce": {
                        "description": "The nonce used when signing the transaction",
                        "$ref": "#/components/schemas/NONCE"
                    },
                    "sender_public_key": {
                        "description": "The key of the sending user",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "sender_vault_id": {
                        "description": "The vault that is the source of the transfer",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "token_id": {
                        "description": "The id of the asset or token transferred",
                        "$ref": "#/components/schemas/ASSET_ID"
                    },
                    "receiver_public_key": {
                        "description": "The key of the receiving user",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "receiver_vault_id": {
                        "description": "The target vault for the transfer",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "expiration_timestamp": {
                        "description": "The expiration timestamp of the transfer transaction",
                        "$ref": "#/components/schemas/EXPIRATION_TIMESTAMP"
                    },
                    "signature": {
                        "description": "The transfer signature details",
                        "$ref": "#/components/schemas/SIGNATURE"
                    },
                    "fee_info_user": {
                        "description": "The fee information for this transfer",
                        "$ref": "#/components/schemas/FEE_LIMIT"
                    },
                    "fee_info_exchange": {
                        "description": "Information about the fee taken, and to which vault",
                        "$ref": "#/components/schemas/FEE_LIMIT"
                    }
                }
            },
            "TRANSFER_WITH_ID": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/TRANSFER"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "transaction_id": {
                                "$ref": "#/components/schemas/TXN_ID"
                            }
                        }
                    }
                ]
            },
            "ORDER_ID": {
                "type": "integer",
                "minimum": 0
            },
            "TXN_STATUS": {
                "type": "string",
                "enum": [
                    "SUCCESS",
                    "FAILURE",
                    "PENDING"
                ]
            },
            "MINT_OPERATION_INFO": {
                "type": "object",
                "required": [
                    "name",
                    "nft_type",
                    "owner_key",
                    "contract_address",
                    "collection_id",
                    "content"
                ],
                "properties": {
                    "name": {
                        "description": "The name for the NFT",
                        "$ref": "#/components/schemas/DISPLAY_TEXT"
                    },
                    "nft_type": {
                        "description": "The type of the NFT (contract type)",
                        "type": "string",
                        "enum": [
                            "ERC721",
                            "ERC1155"
                        ]
                    },
                    "stark_key": {
                        "description": "The stark key of the owner of the NFT",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "contract_address": {
                        "description": "The contract address for the NFT contract",
                        "$ref": "#/components/schemas/ETH_ADDRESS"
                    },
                    "collection_id": {
                        "description": "The id of the collection to assign the new NFT(s) to",
                        "$ref": "#/components/schemas/COLLECTION_ID"
                    },
                    "content": {
                        "description": "A link to content of the NFT; usually some kind of URL",
                        "type": "string",
                        "minLength": 1
                    },
                    "description": {
                        "description": "The description of the NFT",
                        "$ref": "#/components/schemas/DISPLAY_TEXT"
                    },
                    "amount": {
                        "description": "How many NFTs to mint (defaults to 1)",
                        "type": "integer",
                        "minimum": 1
                    },
                    "metadata_uri": {
                        "description": "A pointer to further metadata",
                        "type": "string"
                    },
                    "keywords": {
                        "description": "Keywords for the minted NFT",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/KEYWORD"
                        }
                    },
                    "royalties": {
                        "description": "Royalties to distribute for the minted NFTs",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "recipient_key": {
                                    "$ref": "#/components/schemas/STARK_KEY"
                                },
                                "recipient_vault_id": {
                                    "$ref": "#/components/schemas/VAULT_ID"
                                },
                                "fee": {
                                    "$ref": "#/components/schemas/FEE_LIMIT"
                                }
                            }
                        }
                    }
                }
            },
            "MINT_WITH_ID": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/MINT_OPERATION_INFO"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "transaction_id": {
                                "$ref": "#/components/schemas/TXN_ID"
                            },
                            "minting_blob": {
                                "$ref": "#/components/schemas/MINTING_BLOB"
                            },
                            "vault_id": {
                                "$ref": "#/components/schemas/VAULT_ID"
                            },
                            "asset_id": {
                                "$ref": "#/components/schemas/ASSET_ID"
                            },
                            "proof": {
                                "$ref": "#/components/schemas/MERKLE_PROOF"
                            }
                        }
                    }
                ]
            },
            "MINTING_BLOB": {
                "type": "string",
                "minLength": 1
            },
            "TXN_ID": {
                "type": "integer",
                "minimum": 0
            },
            "DISPLAY_TEXT": {
                "description": "Text that is to be displayed to users",
                "type": "string"
            },
            "FILTER": {
                "oneOf": [
                    {
                        "type": "object",
                        "properties": {
                            "keywords": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/KEYWORD"
                                }
                            }
                        }
                    },
                    {
                        "type": "object",
                        "properties": {
                            "attributes": {
                                "$ref": "#/components/schemas/METADATA_DICT"
                            }
                        }
                    },
                    {
                        "type": "object",
                        "properties": {
                            "names": {
                                "type": "array",
                                "description": "A list of collection names to look for. Matching for substrings, case insensitive.",
                                "items": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ]
            },
            "ASSET_FILTER": {
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/FILTER"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "collection_id": {
                                "description": "The collection id that contains the assets to retrieve",
                                "$ref": "#/components/schemas/COLLECTION_ID"
                            }
                        }
                    },
                    {
                        "type": "object",
                        "properties": {
                            "contract_address": {
                                "description": "The address of the L1 contracts that minted the assets to retrieve",
                                "$ref": "#/components/schemas/ETH_ADDRESS"
                            }
                        }
                    }
                ]
            },
            "FEE_INFO": {
                "description": "Information about the fee collected",
                "type": "object",
                "properties": {
                    "amount_taken": {
                        "description": "Actual amount of fee taken",
                        "type": "integer",
                        "minimum": 0
                    },
                    "destination_vault_id": {
                        "description": "The vault to which the fee was transferred",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "destination_stark_key": {
                        "description": "The stark key for the destination vault",
                        "$ref": "#/components/schemas/STARK_KEY"
                    }
                }
            },
            "SETTLEMENT_INFO": {
                "description": "An object describing the settlement itself - how much was transferred, and fees collected",
                "type": "object",
                "properties": {
                    "party_a_sold": {
                        "description": "Amount of assets transferred from A to B",
                        "type": "integer",
                        "minimum": 0
                    },
                    "party_b_sold": {
                        "description": "Amount of assets transferred from B to A",
                        "type": "integer",
                        "minimum": 0
                    },
                    "party_a_fee_info": {
                        "description": "Exchange fee for party A",
                        "$ref": "#/components/schemas/FEE_INFO"
                    },
                    "party_b_fee_info": {
                        "description": "Exchange fee for party B",
                        "$ref": "#/components/schemas/FEE_INFO"
                    }
                }
            },
            "SETTLEMENT": {
                "description": "A settlement of 2 orders (buy+sell) for NFTs",
                "type": "object",
                "properties": {
                    "settlement_info": {
                        "$ref": "#/components/schemas/SETTLEMENT_INFO"
                    },
                    "party_a_order": {
                        "$comment": "type of order must be BUY",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/ORDER"
                            },
                            {
                                "type": "object",
                                "properties": {
                                    "stark_key": {
                                        "$ref": "#/components/schemas/STARK_KEY"
                                    }
                                }
                            }
                        ]
                    },
                    "party_b_order": {
                        "$comment": "type of order must be SELL",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/ORDER"
                            },
                            {
                                "type": "object",
                                "properties": {
                                    "stark_key": {
                                        "$ref": "#/components/schemas/STARK_KEY"
                                    }
                                }
                            }
                        ]
                    }
                }
            },
            "SETTLEMENT_WITH_ID": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/SETTLEMENT"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "transaction_id": {
                                "$ref": "#/components/schemas/TXN_ID"
                            }
                        }
                    }
                ]
            },
            "ORDER": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "BUY",
                            "SELL"
                        ]
                    },
                    "vault_id_sell": {
                        "description": "The vault id for the first party in the order",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "token_sell": {
                        "description": "The 1st asset id to buy/sell",
                        "$ref": "#/components/schemas/ASSET_ID"
                    },
                    "amount_sell": {
                        "description": "The 1st amount - to sell",
                        "type": "integer",
                        "minimum": 1
                    },
                    "vault_id_buy": {
                        "description": "The vault id for the second party in the order",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "token_buy": {
                        "description": "The 2nd asset id to buy/sell",
                        "$ref": "#/components/schemas/ASSET_ID"
                    },
                    "amount_buy": {
                        "description": "The 2nd amount - to buy",
                        "type": "integer",
                        "minimum": 1
                    },
                    "expiration_timestamp": {
                        "description": "The order expiration time",
                        "$ref": "#/components/schemas/EXPIRATION_TIMESTAMP"
                    },
                    "nonce": {
                        "$ref": "#/components/schemas/NONCE"
                    },
                    "signature": {
                        "description": "The user's signature on the order",
                        "$ref": "#/components/schemas/SIGNATURE"
                    },
                    "fee_info": {
                        "$ref": "#/components/schemas/FEE_LIMIT"
                    }
                }
            },
            "TIMESTAMP": {
                "description": "A UTC timestamp",
                "type": "integer",
                "minimum": 0
            },
            "EXPIRATION_TIMESTAMP": {
                "type": "integer",
                "minimum": 0,
                "maximum": 4194303,
                "$comment": "upper limit is 2^22-1, taken from StarkEx code - ExpirationTimestampField"
            },
            "ORDER_WITH_ID": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/ORDER"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "order_id": {
                                "$ref": "#/components/schemas/ORDER_ID"
                            }
                        }
                    }
                ]
            },
            "VAULT_ID": {
                "description": "A vault id, represented as a hex number",
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{16}$",
                "$comment": "This is a superset of both validium and rollup vault ranges"
            },
            "NFT_COLLECTION_INFO": {
                "type": "object",
                "properties": {
                    "name": {
                        "description": "The name of the NFT collection",
                        "type": "string"
                    },
                    "description": {
                        "description": "A description of the NFT collection",
                        "type": "string"
                    },
                    "contract_address": {
                        "description": "Address of the NFT contract on L1",
                        "$ref": "#/components/schemas/ETH_ADDRESS"
                    },
                    "collection_image_url": {
                        "description": "A URL to an image for the collection",
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "ERC721",
                            "ERC1155"
                        ]
                    },
                    "keywords": {
                        "description": "List of keywords associated with this collection",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/KEYWORD"
                        }
                    },
                    "metadata_scheme": {
                        "description": "Schema of metadata properties for NFTs in this collection",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "is_in_blob": {
                                    "description": "Designates whether this key is part of the minting blob",
                                    "type": "boolean"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "TEXT",
                                        "DISCRETE",
                                        "ENUM"
                                    ]
                                }
                            }
                        }
                    }
                }
            },
            "RESULT_PAGE_REQUEST": {
                "type": "object",
                "properties": {
                    "continuation_token": {
                        "description": "a pointer to the last element of the delivered page, use this token in a subsequent query to obtain the next page",
                        "type": "string"
                    },
                    "chunk_size": {
                        "type": "integer",
                        "minimum": 1
                    }
                },
                "required": [
                    "chunk_size"
                ]
            },
            "ASSET_WITH_TXN_HISTORY": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/ASSET"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "history": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/ASSET_HISTORY_ITEM"
                                }
                            }
                        }
                    }
                ]
            },
            "COMMON_ASSET_PROPERTIES": {
                "type": "object",
                "properties": {
                    "type": {
                        "anyOf": [
                            {
                                "type": "string",
                                "enum": [
                                    "ETH",
                                    "ERC721",
                                    "ERC1155",
                                    "ERC20"
                                ]
                            },
                            {
                                "$comment": "Allow future asset types to be added and pass validation",
                                "type": "string"
                            }
                        ]
                    },
                    "owner_key": {
                        "description": "The stark key of the owner of the NFT",
                        "$ref": "#/components/schemas/STARK_KEY"
                    },
                    "asset_id": {
                        "$ref": "#/components/schemas/ASSET_ID"
                    }
                }
            },
            "ETH_ASSET": {
                "allOf": [
                    {
                        "type": "object",
                        "properties": {
                            "amount": {
                                "description": "The amount of the asset",
                                "type": "integer",
                                "minimum": 0
                            }
                        }
                    },
                    {
                        "$ref": "#/components/schemas/COMMON_ASSET_PROPERTIES"
                    }
                ]
            },
            "ERC20_ASSET": {
                "allOf": [
                    {
                        "type": "object",
                        "properties": {
                            "amount": {
                                "description": "The amount of the asset",
                                "type": "integer",
                                "minimum": 0
                            },
                            "contract_address": {
                                "description": "Address of the NFT contract on L1",
                                "$ref": "#/components/schemas/ETH_ADDRESS"
                            }
                        }
                    },
                    {
                        "$ref": "#/components/schemas/COMMON_ASSET_PROPERTIES"
                    }
                ]
            },
            "COMMON_NFT_ASSET_PROPERTIES": {
                "type": "object",
                "properties": {
                    "name": {
                        "description": "The name of the NFT",
                        "type": "string"
                    },
                    "description": {
                        "description": "A description of the NFT",
                        "type": "string"
                    },
                    "contract_address": {
                        "description": "Address of the NFT contract on L1",
                        "$ref": "#/components/schemas/ETH_ADDRESS"
                    },
                    "collection_id": {
                        "description": "The id of the collection this NFT belongs to",
                        "$ref": "#/components/schemas/COLLECTION_ID"
                    },
                    "minting_blob": {
                        "description": "For an NFT, the blob included in the asset id hash",
                        "type": "string"
                    },
                    "content": {
                        "description": "The content of the NFT (or link to it)",
                        "type": "string"
                    },
                    "proof": {
                        "$ref": "#/components/schemas/MERKLE_PROOF"
                    },
                    "metadata": {
                        "$ref": "#/components/schemas/METADATA_DICT"
                    },
                    "keywords": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/KEYWORD"
                        }
                    }
                }
            },
            "ERC721_ASSET": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/COMMON_ASSET_PROPERTIES"
                    },
                    {
                        "$ref": "#/components/schemas/COMMON_NFT_ASSET_PROPERTIES"
                    }
                ]
            },
            "ERC1155_ASSET": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/COMMON_ASSET_PROPERTIES"
                    },
                    {
                        "$ref": "#/components/schemas/COMMON_NFT_ASSET_PROPERTIES"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "amount": {
                                "description": "The amount of the asset",
                                "type": "integer",
                                "minimum": 0
                            }
                        }
                    }
                ]
            },
            "ASSET": {
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/ETH_ASSET"
                    },
                    {
                        "$ref": "#/components/schemas/ERC20_ASSET"
                    },
                    {
                        "$ref": "#/components/schemas/ERC721_ASSET"
                    },
                    {
                        "$ref": "#/components/schemas/ERC1155_ASSET"
                    }
                ]
            },
            "MERKLE_PROOF": {
                "type": "object",
                "properties": {
                    "path": {
                        "$ref": "#/components/schemas/MERKLE_PATH"
                    },
                    "root": {
                        "description": "The state root where the path is relevant",
                        "$ref": "#/components/schemas/STATE_ROOT"
                    }
                }
            },
            "METADATA_DICT": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "key": {
                            "type": "string"
                        },
                        "value": {
                            "type": "string"
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "TEXT",
                                "DISCRETE",
                                "ENUM"
                            ]
                        }
                    }
                }
            },
            "STARK_KEY": {
                "$ref": "#/components/schemas/NUM_AS_HEX"
            },
            "NUM_AS_HEX": {
                "description": "An integer number in hex format (0x...)",
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]+$"
            },
            "ETH_ADDRESS": {
                "type": "string",
                "$comment": "An ethereum address",
                "description": "an ethereum address represented as 40 hex digits",
                "pattern": "^0x[a-fA-F0-9]{40}$"
            },
            "ASSET_ID": {
                "description": "The asset id of for an NFT (ERC721) asset. 32 bytes with 5 MSB zeroed",
                "type": "string",
                "pattern": "^0x0[0-7]{1}[a-fA-F0-9]{62}$"
            },
            "ASSET_TYPE": {
                "description": "The asset type. A uint256 value, up to 2^31, as hex digits",
                "$ref": "#/components/schemas/NUM_AS_HEX"
            },
            "MERKLE_PATH": {
                "description": "A series of bytes denoting a path in a merkle tree. Bytes given as pairs of hex digits",
                "$ref": "#/components/schemas/BYTES"
            },
            "SIGNATURE": {
                "description": "A signature provided as a pair of numbers",
                "type": "object",
                "properties": {
                    "r": {
                        "$ref": "#/components/schemas/BYTES"
                    },
                    "s": {
                        "$ref": "#/components/schemas/BYTES"
                    }
                }
            },
            "BYTES": {
                "description": "A series of bytes denoted as pairs of hex digits",
                "type": "string",
                "pattern": "^0x([a-fA-F0-9]{2})+$"
            },
            "TOKEN_ID": {
                "description": "An ID for a token",
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{64}$",
                "$comment": "A generalized case - 251 bits (and a bit extra)"
            },
            "STATE_ROOT": {
                "description": "The global state root",
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{64}$",
                "$comment": "251 bits (and a bit extra)"
            },
            "FEE_LIMIT": {
                "description": "Fee limit information provided by the user",
                "type": "object",
                "properties": {
                    "token_id": {
                        "description": "The token id of the fee",
                        "$ref": "#/components/schemas/TOKEN_ID"
                    },
                    "vault_id": {
                        "description": "The id of the source/target vault",
                        "$ref": "#/components/schemas/VAULT_ID"
                    },
                    "fee_limit": {
                        "description": "The fee limit",
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9223372036854775808,
                        "$comment": "upper limit is 2^63, taken from definition of AmountField"
                    }
                }
            },
            "KEYWORD": {
                "description": "A label, alphanumeric English + underscore, with no spaces",
                "type": "string",
                "pattern": "^[a-zA-Z0-9_]+$"
            },
            "COLLECTION_ID": {
                "type": "integer",
                "minimum": 0
            },
            "NONCE": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647,
                "$comment": "Maximum is 2^31-1, taken from definition of NonceField in StarkEx"
            }
        },
        "errors": {
            "ASSET_NOT_FOUND": {
                "code": 1,
                "message": "Requested asset was not found"
            },
            "COLLECTION_NOT_FOUND": {
                "code": 2,
                "message": "Requested collection not found"
            },
            "INVALID_COLLECTION_INFO": {
                "code": 3,
                "message": "Given collection information is invalid"
            },
            "INVALID_MINT_INPUT": {
                "code": 4,
                "message": "Invalid mint operation information"
            },
            "TRANSACTION_NOT_FOUND": {
                "code": 5,
                "message": "The requested transaction was not found"
            },
            "ORDER_NOT_FOUND": {
                "code": 6,
                "message": "The requested order was not found"
            },
            "SUBSCRIPTION_UNSUCCESSFUL": {
                "code": 7,
                "message": "Unable to establish subscription"
            }
        }
    }
}