Skip to main content

Create a listing

You can create a listing for your item using the Phosphor API.

You can use the API to create item-level and collection-level listings. You can define first-come first-serve and allowlist policies when creating a listing. You can also create a free mint listing.

info

You can currently only create collection-level listings on ERC-721 collections.

Items must be locked before any listings can be created.

Issue a POST request to the listings endpoint.

POST https://admin-api.phosphor.xyz/v1/listings
Example payload
{
  "item_id": "12b4659a-0796-4021-b21e-a376494b674c",
  "quantity_listed": 1,
  "price": "25000",
  "currency": "USD",
  "payment_providers": ["STRIPE", "MINT_VOUCHER"],
  "max_quantity_per_tx": 1,
  "policy": {
    "max_per_user": 1,
    "payment_session_duration": {
      "timeout_seconds": 600,
    },
    "email_claim_duration": 7200,
    "item_assignment_strategy": "AUTOMATIC",
    "type": "FCFS",
    "tx_payer": "SELLER"
  },
  "settlement_currency": {
    "MINT_VOUCHER": "USD"
  },
  "start_time": "2022-11-08T09:00:00+00:00",
  "end_time": "2022-12-08T09:00:00+00:00",
  "campaign_id": "762f86b9-3a45-43ef-a617-2562839a20ed"
}
  • item_id or collection_id - You must specify an item ID or collection ID, but not both. If an item ID is specified, the listing is created on the item level. If a collection ID is specified, the listing is created on the collection level.
  • quantity_listed - Quantity of items for sale.
  • price - Price of the items in the corresponding decimals. For ERC-20 tokens, this is usually 10e18. For fiat currencies, this is in cents.
  • currency - Supported currencies in USD, EUR, or ETH.
  • payment_providers - List of payment providers to allow payments from. Accepted values are "STRIPE", "MINT_VOUCHER", "ORGANIZATION", and "EMAIL_CLAIM". The selected payment providers must already be configured in your organization.
  • max_quantity_per_tx - The maximum quantity of items allowed for purchase in each transaction.
  • policy - Listing policy with rules and conditions that dictate how the item or collection should sell.
    • max_per_user - The maximum quantity of items allowed for each buyer.
    • payment_session_duration - Duration of a checkout session during which the items are reserved for the buyer. Payment session duration can't be less than 60 seconds. It can't be more than 1 hour for Stripe, and 15 minutes for mint vouchers. Payment session duration can't be configured for an email claim payment provider.
      • timeout_seconds - Timeout of the payment session in seconds.
      • provider_override - Timeout of the payment session to override for different providers, if desired.
    • email_claim_duration - Duration of the time period during which email claims are active, if the the listing is fulfilled using emails. Email claim duration can't be less than 1 hour or exceed 30 days. If left unspecified, email claims expire in 30 days.
    • item_assignment_strategy: AUTOMATIC or RANDOM. If AUTOMATIC, orders are fulfilled from the lowest token ID available. If RANDOM, items are assigned to orders randomly.
    • tx_payer - Payer of the transaction fees for token transfers, if the listing is fulfilled using emails. The default is SELLER.
    • type - Type of the policy, FCFS or ALLOW_LIST. If not specified, listing is FCFS by default.
    • eth_addresses - List of Ethereum addresses allowed to buy, if policy is ALLOW_LIST.
    • email_address - List of email addresses allowed to buy, if policy is ALLOW_LIST.
    • snapshot_id - Snapshot of Ethereum addresses allowed to buy, if policy is ALLOW_LIST.
  • settlement_currency - Can be configured for MINT_VOUCHER as a payment provider. It accepts ETH, USD or EUR. See listing currencies for more information.
  • start_time - Start time for the listing after which purchase intents can be made. This field accepts a timezone-aware datetime string. The default is the time of the request.
  • end_time - Expiration time for the listing before which purchase intents can be made. This field accepts a timezone-aware datetime string. If not specified, the listing is active until cancelled.
  • campaign_id - The marketing campaign to use for this listing.
Example response
{
  "id": "4e339560-5c6c-495a-bfe3-0a30e3519983",
  "status": "ACTIVE",
  "quantity_listed": 1,
  "quantity_remaining": 1,
  "sale_type": "DEFAULT",
  "policy": {
    "type": "FCFS",
    "max_per_user": 1,
    "payment_session_duration": {
      "timeout_seconds": 600,
    },
    "email_claim_duration": 7200,
    "item_assignment_strategy": "AUTOMATIC",
    "tx_payer": "SELLER"
  },
  "start_time": "2022-11-08T09:00:00+00:00",
  "end_time": "2022-12-08T09:00:00+00:00",
  "collection_id": null,
  "item_id": "12b4659a-0796-4021-b21e-a376494b674c",
  "price": "25000",
  "currency": "USD",
  "settlement_currency": {
    "MINT_VOUCHER": "USD"
  },
  "max_quantity_per_tx": 1,
  "payment_providers": ["STRIPE", "MINT_VOUCHER"],
  "campaign_id": "762f86b9-3a45-43ef-a617-2562839a20ed"
}

Create an item-level listing​

Specify an item_id in your listing input. When an item_id is specified, fields that pertain to a collection-level listing, such as item_ids, token_ids, and token_ranges, become incompatible.

Example item-level listing
{
  ...
  "item_id": "12b4659a-0796-4021-b21e-a376494b674c"
  ...
}

Create a collection-level listing​

Specify a collection_id in your listing input. For a collection-level listing, you can specify a list of items for sale by providing a list of item IDs, a list of token IDs, or a list of token ranges. If left unspecified, all items within the collection become available for sale.

Example collection-level listing
{
  ...
  "collection_id": "66e0c43c-d5dd-4e86-8518-69f7655b48f3"
  ...
}
Example using item IDs
{
  ...
  "collection_id": "66e0c43c-d5dd-4e86-8518-69f7655b48f3",
  "item_ids": ["12b4659a-0796-4021-b21e-a376494b674c", "be424b16-f05a-438f-a120-e8b8b0d5b956"]
  ...
}
Example using token IDs
{
  ...
  "collection_id": "66e0c43c-d5dd-4e86-8518-69f7655b48f3",
  "token_ids": [1, 2, 10]
  ...
}
Example using token ranges
{
  ...
  "collection_id": "66e0c43c-d5dd-4e86-8518-69f7655b48f3",
  "token_ranges": [{"from_id": 1, "to_id": 5}, {"from_id": 10, "to_id": 20}]
  ...
}

You can specify multiple token ranges as long as they don't overlap.

Create a listing using an FCFS policy​

Set a first-come first-served policy by setting policy type to FCFS. If left unspecified, the policy field defaults to FCFS.

max_per_user, payment_session_duration, email_claim_duration, item_assignment_strategy, and tx_payer are common fields across all policy types.

Example using FCFS policy
{
  ...
  "policy": {
    "type": "FCFS",
    "max_per_user": 1,
    "payment_session_duration": {
      "timeout_seconds": 600,
    },
    "email_claim_duration": 7200,
    "item_assignment_strategy": "AUTOMATIC",
    "tx_payer": "SELLER",
  }
  ...
}

Create a listing using a LARGE_ALLOW_LIST policy​

The LARGE_ALLOW_LIST type allows you to define and maintain an allow list of eligible addresses. The list is initially created with no addresses and you must edit it with a subsequent call to add any addresses. See editing an allowlist for more detail.

info

This type was introduced after ALLOW_LIST and allows much larger lists. It supports million of entries versus 1000 for ALLOW_LIST and should be preferred when creating an allow list type listing.

Example using LARGE_ALLOW_LIST policy
{
  ...
  "policy": {
    "type": "LARGE_ALLOW_LIST",
  },
  "payment_providers": ["ORGANIZATION"]
  ...
}

Create a listing using an ALLOW_LIST policy​

Set an allowlist policy by setting policy type to ALLOW_LIST. Supply a list of allowed Ethereum address, email addresses, or snapshot IDs to restrict the purchase to.

Example using ALLOW_LIST policy with Ethereum addresses
{
  ...
  "policy": {
    "type": "ALLOW_LIST",
    "eth_addresses": ["0xa99d7eD4bb4E3EeFEd18a0269Be46Aa8C49Ab165", "0xabf518e9B51D8DfD936E552d22B35Cfd8bDB48a5"]
  },
  "payment_providers": ["STRIPE"]
  ...
}
Example using ALLOW_LIST policy with email addresses
{
  ...
  "policy": {
    "type": "ALLOW_LIST",
    "email_addresses": ["aaa@aaa.com", "bbb@bbb.com"]
  },
  "payment_providers": ["STRIPE"]
  ...
}
Example using ALLOW_LIST policy with a snapshot ID
{
  ...
  "policy": {
    "type": "ALLOW_LIST",
    "snapshot_id": "1ab62c19-bb5c-4c0e-b788-454dd16ca257"
  },
  "payment_providers": ["STRIPE"]
  ...
}

Create a free mint listing with EMAIL_CLAIM as the payment provider​

Create a free mint drop by setting the listing price to 0 and the payment provider to EMAIL_CLAIM.

When a listing is created as free mint, you have the option to have organization pay the gas (tx_payer=SELLER) or buyer (tx_payer=BUYER) pay the gas. The buyer receives the email claim in their mailbox shortly afterwards. You may specify customize other fields, such as, max_per_user, email_claim_duration, tx_payer, and type in the policy field in your listing. Any purchase intents against the listing are immediately confirmed and fulfillment begins.

Example free mint listing
{
  ...
  "price": "0",
  "payment_providers": ["EMAIL_CLAIM"],
  "policy": {
    "max_per_user": 1,
    "email_claim_duration": 3600,
    "tx_payer": "BUYER",
    "type": "ALLOW_LIST",
    "email_addresses": ["aaa@aaa.com", "bbb@bbb.com"]
  }
  ...
}

Create a free mint + free gas listing with ORGANIZATION as the payment provider​

Create a free mint drop by setting the listing price to 0 and the payment provider to ORGANIZATION.

When a listing is created as free mint, free consumer gas, any purchase intents against the listing are immediately confirmed and fulfillment begins. The organization will pay for mint (transfer) of the items also. The consumer is sent the item directly to their wallet address at no cost to them. However, you may specify fields such as max_per_user, and type in the policy field to customize your listing.

Example Organization pays gas listing
{
  ...
  "price": "0",
  "payment_providers": ["ORGANIZATION"],
  "policy": {
    "max_per_user": 1,
  }
  ...
}

Last updated on