CreateMetadataBidRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/immutable/main/json-schema/immutable-create-metadata-bid-request-body-schema.json",
  "title": "CreateMetadataBidRequestBody",
  "description": "Request body for creating a metadata bid. Exactly one of `metadata_id`\nor `metadata_criteria` must be provided.\n",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immutable-orders-api-openapi.yml#/components/schemas/CreateMetadataBidRequestBody",
  "type": "object",
  "properties": {
    "account_address": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$"
    },
    "order_hash": {
      "type": "string"
    },
    "metadata_id": {
      "type": "string",
      "format": "uuid",
      "description": "Metadata identifier that matching NFTs must have to fulfill this bid. Mutually exclusive with `metadata_criteria`."
    },
    "metadata_criteria": {
      "type": "array",
      "description": "Field-level metadata filters that matching NFTs must satisfy to fulfill this bid. Mutually exclusive with `metadata_id`.",
      "items": {
        "$ref": "#/$defs/MetadataFieldFilter"
      },
      "minItems": 1
    },
    "buy": {
      "type": "array",
      "description": "Buy item for metadata bid should either be ERC721 or ERC1155 collection item",
      "items": {
        "$ref": "#/$defs/AssetCollectionItem"
      },
      "minItems": 1,
      "maxItems": 1
    },
    "fees": {
      "type": "array",
      "description": "Buy fees should only include maker marketplace fees and should be no more than two entries as more entires will incur more gas. It is best practice to have this as few as possible.",
      "items": {
        "$ref": "#/$defs/Fee"
      },
      "minItems": 0,
      "maxItems": 2
    },
    "end_at": {
      "type": "string",
      "description": "Time after which the Order is considered expired",
      "format": "date-time"
    },
    "protocol_data": {
      "$ref": "#/$defs/ProtocolData"
    },
    "salt": {
      "type": "string",
      "description": "A random value added to the create Order request"
    },
    "sell": {
      "type": "array",
      "description": "Sell item for metadata bid should be an ERC20 item",
      "items": {
        "$ref": "#/$defs/ERC20Item"
      },
      "minItems": 1,
      "maxItems": 1
    },
    "signature": {
      "type": "string",
      "description": "Digital signature generated by the user for the specific Order"
    },
    "start_at": {
      "type": "string",
      "description": "Time after which Order is considered active",
      "format": "date-time"
    }
  },
  "required": [
    "account_address",
    "order_hash",
    "buy",
    "sell",
    "fees",
    "end_at",
    "start_at",
    "protocol_data",
    "salt",
    "signature"
  ],
  "$defs": {
    "AssetCollectionItem": {
      "oneOf": [
        {
          "$ref": "#/$defs/ERC721CollectionItem"
        },
        {
          "$ref": "#/$defs/ERC1155CollectionItem"
        }
      ]
    },
    "ERC1155CollectionItem": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Token type user is offering, which in this case is ERC1155",
          "enum": [
            "ERC1155_COLLECTION"
          ]
        },
        "contract_address": {
          "type": "string",
          "description": "Address of ERC1155 collection",
          "pattern": "^0x[a-fA-F0-9]{40}$"
        },
        "amount": {
          "type": "string",
          "description": "A string representing the price at which the user is willing to sell the token. This value is provided in the smallest unit of the token (e.g., wei for Ethereum).",
          "pattern": "\\d+"
        }
      },
      "required": [
        "type",
        "contract_address",
        "amount"
      ]
    },
    "ERC20Item": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Token type user is offering, which in this case is ERC20",
          "enum": [
            "ERC20"
          ]
        },
        "contract_address": {
          "type": "string",
          "description": "Address of ERC20 token",
          "pattern": "^0x[a-fA-F0-9]{40}$"
        },
        "amount": {
          "type": "string",
          "description": "A string representing the price at which the user is willing to sell the token. This value is provided in the smallest unit of the token (e.g., wei for Ethereum).",
          "pattern": "\\d+"
        }
      },
      "required": [
        "type",
        "contract_address",
        "amount"
      ]
    },
    "ERC721CollectionItem": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Token type user is offering, which in this case is ERC721",
          "enum": [
            "ERC721_COLLECTION"
          ]
        },
        "contract_address": {
          "type": "string",
          "description": "Address of ERC721 collection",
          "pattern": "^0x[a-fA-F0-9]{40}$"
        },
        "amount": {
          "type": "string",
          "description": "A string representing the price at which the user is willing to sell the token. This value is provided in the smallest unit of the token (e.g., wei for Ethereum).",
          "pattern": "\\d+"
        }
      },
      "required": [
        "type",
        "contract_address",
        "amount"
      ]
    },
    "Fee": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "string",
          "description": "Fee payable to recipient upon settlement",
          "pattern": "\\d+"
        },
        "type": {
          "type": "string",
          "description": "Fee type",
          "enum": [
            "ROYALTY",
            "MAKER_ECOSYSTEM",
            "TAKER_ECOSYSTEM",
            "PROTOCOL"
          ]
        },
        "recipient_address": {
          "type": "string",
          "description": "Wallet address of fee recipient",
          "pattern": "^0x[a-fA-F0-9]{40}$"
        }
      },
      "required": [
        "type",
        "amount",
        "recipient_address"
      ]
    },
    "MetadataFieldFilter": {
      "type": "object",
      "description": "A field-level filter used to match NFTs for a metadata bid. The\n`field_name` is either a top-level metadata field (`name`, `image`,\n`description`, `animation_url`, `external_url`, `youtube_url`) or an\nattribute identified by the `attribute:<trait_type>` prefix (e.g.\n`attribute:Background`). Values match case-insensitively; multiple\nvalues are OR'd, multiple filters on a bid are AND'd.\n",
      "properties": {
        "field_name": {
          "type": "string",
          "description": "The metadata field name (top-level field or `attribute:<trait_type>`)"
        },
        "values": {
          "type": "array",
          "description": "The metadata field values to match against (OR semantics)",
          "items": {
            "type": "string"
          },
          "minItems": 1
        }
      },
      "required": [
        "field_name",
        "values"
      ]
    },
    "ProtocolData": {
      "type": "object",
      "properties": {
        "order_type": {
          "type": "string",
          "description": "Seaport order type. Orders containing ERC721 tokens will need to pass in the order type as FULL_RESTRICTED while orders with ERC1155 tokens will need to pass in the order_type as PARTIAL_RESTRICTED",
          "enum": [
            "FULL_RESTRICTED",
            "PARTIAL_RESTRICTED"
          ]
        },
        "counter": {
          "type": "string",
          "description": "big.Int or uint256 string for order counter"
        },
        "zone_address": {
          "type": "string",
          "description": "Immutable zone address"
        },
        "seaport_address": {
          "type": "string",
          "description": "Immutable Seaport contract address"
        },
        "seaport_version": {
          "type": "string",
          "description": "Immutable Seaport contract version"
        }
      },
      "required": [
        "order_type",
        "counter",
        "zone_address",
        "seaport_address",
        "seaport_version"
      ]
    }
  }
}