Find compute resources on the marketplace

The Fluence compute marketplace is a decentralized platform where you can find and rent compute resources from various providers worldwide. Each provider has offers with different geographies, configurations, and prices. The marketplace API helps you discover resources that meet your specific requirements.

In this guide, you'll learn how to:

Search for available compute offers
Filter resources based on your requirements
Understand and compare different provider offerings
Select the optimal resources for your needs

Search for available offers

The marketplace offers a powerful API endpoint that allows you to search for available compute resources with specific filters:

POST https://api.fluence.dev/marketplace/offers

Request parameters

You can use the request body to filter offers based on your specific requirements. All filters are optional, you can use them to find whether there are offers that match your requirements.

Example of a request body with all filters applied:

{
  "basicConfiguration": "cpu-8-ram-16gb-storage-25gb", // optional
  "additionalResources": {
    "storage": [
      // optional
      {
        "type": "NVMe",
        "megabytes": 20480 // in MiB
      }
    ]
  },
  "hardware": {
    // optional
    "cpu": [
      // optional
      {
        "manufacturer": "AMD",
        "architecture": "Zen"
      }
    ],
    "memory": [
      // optional
      {
        "type": "DDR",
        "generation": "5"
      }
    ],
    "storage": [
      // optional
      {
        "type": "NVMe"
      }
    ]
  },
  "datacenter": {
    // optional
    "countries": ["FR"]
  },
  "maxTotalPricePerEpochUsd": "12.57426" // optional
}

Let's break down the request body parameters and their usage

Basic configuration

A predefined configuration string that specifies a common resource profile. Use this for quick filtering without specifying individual resources

Example:

{
  "basicConfiguration": "cpu-8-ram-16gb-storage-25gb"
}

This filter would show offers with 8 CPU cores, 16GB RAM, and 25GB storage.

To get the list with names of all available basic configurations on the marketplace, you can use specific endpoint. Read more about it in the Basic configurations available on the Marketplace section.

Hardware specifications constraints

If you need specific CPU architecture or storage type, you can filter based on hardware requirements. To get the list of all available hardware specifications on the marketplace, you can use specific endpoint, read more about it in the Hardware specifications available on the marketplace section.

hardware
- Specific hardware requirements for the compute resources.
- Fields:
  - cpu
    - manufacturer : CPU manufacturer (e.g., "AMD", "Intel")
    - architecture : CPU architecture (e.g., "Zen", "x86_64")
  - memory
    - type : Memory type (e.g., "DDR")
    - generation : Memory generation (e.g., "4", "5")
  - storage
    - type : Storage type - one of: "HDD", "SSD", or "NVMe"

Example:

{
  "hardware": {
    "cpu": [
      {
        "manufacturer": "AMD"
      }
    ],
    "memory": [
      {
        "type": "DDR",
        "generation": "5"
      }
    ],
    "storage": [
      {
        "type": "NVMe"
      }
    ]
  }
}

Datacenter constraints

API allows you to filter datacenters by country. To get the list of all available countries on the marketplace, you can use specific endpoint, read more about it in the Datacenter countries available on the marketplace section.

datacenter (object)
- Geographic constraints for the compute resources.
- Fields:
  - countries (array of strings): ISO country codes where you want your resources to be located (e.g., ["FR", "DE"] for France and Germany)

Example:

{
  "datacenter": {
    "countries": ["FR", "DE"]
  }
}

Additional resources

If you need additional resources beyond the basic configuration, you can specify them in the request body to get offers that have enough additional resources to satisfy your requirements. Currently, only STORAGE is available as additional resource. Additional resources are hardware resources that are not included in the basic configuration, list of all hardware that you can use as additional resources is available in the Hardware specifications available on the marketplace section.

additionalResources
- Additional resources you need beyond the basic configuration.
- Fields:
  - storage
    - type : Type of storage - one of: "HDD", "SSD", or "NVMe"
    - megabytes : Required storage size in Mebibytes (MiB)

tip

To get the target value in Mebibytes (MiB) from Gigabytes (GB), use the following formula: 1 GiB = 1024 * 1 GB. For example, if you need 10 GB of storage, you should set megabytes to 10240.

Example:

{
  "additionalResources": {
    "storage": [
      {
        "type": "NVMe",
        "megabytes": 20480
      }
    ]
  }
}

Maximum price per epoch constraint

You can apply filter for the max price per epoch (24 hours) in USDC that you're willing to pay for the resources you've specified in the request body: both basic configuration and additional resources.

maxTotalPricePerEpochUsd - Expressed as a string to handle decimal precision (e.g. "12.50")

Example:

{
  "maxTotalPricePerEpochUsd": "12.5"
}

Response structure

When you send a request to /marketplace/offers, you'll receive a response containing an array of offers that match your criteria. Each offer represents a unique configuration available from a specific provider in a particular data center. The response is an array of objects, each object represents an offer from a provider for some basic configuration. To get the list of all available basic configurations, you can use specific endpoint, read more about it in the Basic Configurations available on the marketplace section.

General structure of the response for a single object:

[
  {
    "configuration": {
      "slug": string,
      "price": string
    },
    "resources": [
      {
        "type": string,
        "metadata": {...},
        "price": string
      }
    ],
    "datacenter": {
      "countryCode": string,
      "cityCode": string,
      "cityIndex": number,
      "tier": number,
      "certifications": [string]
    },
    "servers": [
      {
        "availableBasicInstances": number,
        "additionalResources": [
            {
                "supply": number,
            "perVmLimit": number | null,
            "type": string,
            "metadata": {...},
            "price": string
          }
        ]
      }
    ],
    "maxAdditionalSupply": [
      {
        "supply": number,
        "perVmLimit": number | null,
      }
    ]
  },
  // More offers with different configurations and prices
]

Let's break down the key components of the response:

Response fields of a single offering object

Configuration

The configuration object represents the basic configuration of the offer. It includes:

slug: The basic configuration identifier. Read more about basic configurations in the Basic Configurations section. Full list of available basic configurations is available at GET /marketplace/basic-configurations.
price: The base price for this configuration (in USDC per epoch)

Example:

{
  "configuration": {
    "slug": "cpu-2-ram-4gb-storage-25gb",
    "price": "0.30698"
  }
}

Resources

The resources array contains details about the base resources included in the offer with the basic configuration. This shows the exact resources that will be allocated to the VM.

Each resource element in the array includes:

type: Resource type, can be one of the following: VCPU, RAM, STORAGE, PUBLIC_IP
metadata: Its type-specific metadata. You can find more details about the metadata for each hardware resource type in the Resources section.
price: The price for this resource per epoch

Example:

{
  "resources": [
    {
      "type": "VCPU",
      "metadata": {
        "manufacturer": "AMD",
        "brand": "EPYC",
        "architecture": "Zen",
        "generation": "2"
      },
      "price": "0.005"
    },
    {
      "type": "RAM",
      "metadata": {
        "type": "DDR",
        "generation": "4"
      },
      "price": "0.002"
    }
    // Other resources (STORAGE, PUBLIC_IP)
  ]
}

This example object represents hardware configuration for the example basic configuration from the previous example.

Datacenter

The datacenter object provides information about the physical location of the resources and the certifications the datacenter holds.

Each datacenter object includes fields:

countryCode: ISO country code
cityCode: LOCODE code for the city
cityIndex: Index if multiple datacenters exist in the same city
tier: Datacenter tier level (1-4, with 4 being highest reliability)
certifications: Array of compliance certifications this datacenter holds

Example:

{
  "datacenter": {
    "countryCode": "FR",
    "cityCode": "PAR",
    "cityIndex": 1,
    "tier": 2,
    "certifications": ["ISO 200027", "SOC2", "ISO 50001:2011", "PCI DSS 3.2"]
  }
}

Servers

The servers array provides information about the actual physical machines available to host your workloads. Each element in this array represents a distinct physical server in the provider's infrastructure.

Each server object includes:

availableBasicInstances: Number of instances with the basic configuration of the object that can be created on this set of resources
additionalResources: Extra resources this specific server can provide beyond the basic configuration.
- supply: Total amount of this resource available on this server. In case of STORAGE, available amount is in Mebibytes (MiB).
- perVmLimit: Maximum amount of this resource that can be allocated to a single VM (null means no limit)
- type: Resource type (currently only STORAGE is supported)
- metadata: Its type-specific metadata. You can find more details about the metadata for each hardware resource type in the hardware specifications available on the marketplace section.
- price: Cost per unit of this resource

Example:

{
  "servers": [
    {
      "availableBasicInstances": 5,
      "additionalResources": [
        {
          "supply": 102400,
          "perVmLimit": 204800,
          "type": "STORAGE",
          "metadata": {
            "type": "NVMe"
          },
          "price": "0.00006"
        }
      ]
    }
    // Other servers
  ]
}

Max additional supply per VM

The maxAdditionalSupply array provides information about the maximum additional resources you can purchase per one instance of VM. Each element in this array represents a distinct resource type and has the following fields:

supply: Total available quantity of this resource type.
perVmLimit: Maximum amount of this resource that can be allocated to a single VM (null means no limit)
type: Resource type (currently only STORAGE is supported)
metadata: Resource-specific details
price: Cost per unit of this resource

note

In case of STORAGE, values in supply and perVmLimit fields are in Mebibytes (MiB).

{
  "maxAdditionalSupply": [
    {
      "supply": 128000,
      "perVmLimit": 204800,
      "type": "STORAGE",
      "metadata": {
        "type": "NVMe"
      },
      "price": "0.00001"
    }
  ]
}

Comparing and selecting offers

The marketplace may return multiple offers that match your criteria. These offers can differ in several ways:

Price: Different providers set different prices for similar configurations
Location: Same configuration might be available in different datacenters
Hardware specs: CPUs might be from different manufacturers or generations
Availability: The number of instances and additional resources varies

For example, you might see two offers for the same basic configuration (e.g., cpu-2-ram-4gb-storage-25gb) but with different pricing:

Offer 1: Base price of $0.30 per epoch in a French datacenter with AMD processors
Offer 2: Base price of $0.27 per epoch in a German datacenter with Intel processors

This allows you to choose based on your priorities - whether that's cost, location, or specific hardware requirements.

Estimate price for a deployment

Before committing to a deployment, you'll often want to know how much it will cost. The /vms/v3/estimate endpoint allows you to calculate the expected price for your deployment based on your configuration requirements and the number of instances you plan to deploy.

POST /vms/v3/estimate

Request parameters

The request body follows a similar structure to the /marketplace/offers endpoint, with the addition of an instances field to specify how many VMs you want to deploy.

Example of a request body with all filters specified:

{
  "constraints": {
    "basicConfiguration": "cpu-2-ram-4gb-storage-25gb",
    "additionalResources": {
      "storage": [
        {
          "type": "NVMe",
          "megabytes": 20480
        }
      ]
    },
    "hardware": {
      "cpu": [
        {
          "manufacturer": "AMD"
        }
      ],
      "storage": [
        {
          "type": "NVMe"
        }
      ]
    },
    "datacenter": {
      "countries": ["FR", "US"]
    },
    "maxTotalPricePerEpochUsd": "1.2"
  },
  "instances": 3
}

constraints: Contains all your requirements for the deployment, identical to the filters used in the /marketplace/offers endpoint.
- basicConfiguration: The predefined VM configuration you want (e.g., "cpu-2-ram-4gb-storage-25gb")
- additionalResources: Extra resources you need beyond the basic configuration
- hardware: Specific hardware requirements (CPU manufacturer, storage type, etc.)
- datacenter: Geographic constraints for your deployment
- maxTotalPricePerEpochUsd: Maximum price per epoch (24 hours) you're willing to pay
instances: The number of VMs you want to deploy with this configuration

Response structure

The endpoint returns detailed pricing estimation for your proposed deployment.

Example of a response:

{
  "depositAmountUsdc": "7.01532", // totalPricePerEpoch * depositEpochs
  "depositEpochs": 2,
  "totalPricePerEpoch": "3.50766", // total price for all instances per epoch
  "maxPricePerEpoch": "0.35793", // max price for a single instance per epoch
  "instances": 10 // number of instances
}

Response fields

depositAmountUsdc: The total deposit amount required in USDC. This is calculated as totalPricePerEpoch × depositEpochs.
depositEpochs: The number of epochs (days) for which the deposit is calculated. This represents the initial commitment period.
instances: The number of VM instances you requested in your estimate.
maxPricePerEpoch: The maximum price per epoch (24 hours) for a single instance of your configuration.
totalPricePerEpoch: The total price per epoch for all instances combined.

Discovering available options for filter parameters

The Fluence Marketplace API provides several endpoints to help you discover valid values for filter parameters. These endpoints allow you to see what options are available for basic configurations, countries, and hardware specifications.

Basic Configurations available on the marketplace

GET /marketplace/basic_configurations

Retrieves all available predefined resource configurations in the marketplace without specification of concrete hardware. These predefined configurations follow a simple naming pattern: cpu-[cores]-ram-[memory]-storage-[disk]. For example, cpu-2-ram-4gb-storage-25gb represents a VM with 2 CPU cores, 4GB RAM, and 25GB storage.

Response is an array of strings, each string is a basic configuration slug.

Example of a response:

[
  "cpu-2-ram-4gb-storage-25gb",
  "cpu-4-ram-8gb-storage-25gb",
  "cpu-8-ram-16gb-storage-25gb"
  // Other basic configurations
]

Usage: Use these values in the basicConfiguration field of your request parameters to quickly select standard resource profiles. Each configuration string follows the format cpu-[cores]-ram-[memory]-storage-[disk]. For example, "cpu-2-ram-4gb-storage-25gb" represents a configuration with 2 CPU cores, 4GB RAM, and 25GB storage.

Datacenter countries available on the marketplace

GET /marketplace/countries

Lists all countries that have datacenters with available offers in the marketplace.

Example of a response:

["DE", "FR", "GB", "LT", "PL", "US"]

Usage: Use these ISO country codes in the datacenter.countries array of your search parameters to restrict results to specific geographic locations. This is particularly useful for applications with data residency requirements or to minimize latency for specific user regions.

Hardware specifications available on the marketplace

GET /marketplace/hardware

This endpoint returns all hardware specifications available across all providers in the marketplace. The response is an object with arrays of hardware specifications for each resource type.

Example of a successful response:

{
  "cpu": [
    {
      "manufacturer": "AMD",
      "architecture": "Zen"
    },
    {
      "manufacturer": "Intel",
      "architecture": "Cascade Lake"
    }
    // More CPU options
  ],
  "memory": [
    {
      "type": "DDR",
      "generation": "5"
    },
    {
      "type": "DDR",
      "generation": "4"
    }
  ],
  "storage": [
    {
      "type": "SSD"
    },
    {
      "type": "NVMe"
    }
  ]
}

Usage: This endpoint helps you see what hardware specifications are available for filtering. You can use these values in the hardware section of your search parameters:

CPU specifications: Use architecture and manufacturer values to specify CPU requirements
Memory specifications: Use type and generation values to filter by RAM type
Storage types: Use the type value to filter by storage technology (HDD, SSD, or NVMe)

For example, if you need high-performance storage, you might filter for offers with NVMe storage based on the values returned by this endpoint.

Practical workflow

Let's walk through a typical workflow for finding and selecting compute resources if you have any specific requirements:

Determine your requirements:
- Compute power (CPUs, RAM)
- Storage needs
- Geographic constraints
- Budget limitations
Discover available options:
- Use /marketplace/basic_configurations to see standard configurations
- Use /marketplace/countries to see available locations
- Use /marketplace/hardware to see available hardware specs
Search with filters:
- Create a filter based on your requirements
- Send a POST request to /marketplace/offers
Compare and select:
- Review the returned offers
- Compare prices, locations, and hardware specs
- Select the offer that best meets your needs
Proceed to deployment:
- Use the selected offer to create a deployment

The next steps

The Fluence compute marketplace API provides a powerful and flexible way to find and compare compute resources from various providers across the globe. By using the filtering capabilities and understanding the response structure, you can quickly find resources that match your specific requirements including price, location, and hardware specifications.

In the next document, we'll cover how to use your selected offer to create and manage deployments on the Fluence platform.

Search for available offers​

Request parameters​

Basic configuration​

Hardware specifications constraints​

Datacenter constraints​

Additional resources​

Maximum price per epoch constraint​

Response structure​

Response fields of a single offering object​

Configuration​

Resources​

Datacenter​

Servers​

Max additional supply per VM​

Comparing and selecting offers​

Estimate price for a deployment​

Request parameters​

Response structure​

Response fields​

Discovering available options for filter parameters​

Basic Configurations available on the marketplace​

Datacenter countries available on the marketplace​

Hardware specifications available on the marketplace​

Practical workflow​

The next steps​

Search for available offers

Request parameters

Basic configuration

Hardware specifications constraints

Datacenter constraints

Additional resources

Maximum price per epoch constraint

Response structure

Response fields of a single offering object

Configuration

Resources

Datacenter

Servers

Max additional supply per VM

Comparing and selecting offers

Estimate price for a deployment

Request parameters

Response structure

Response fields

Discovering available options for filter parameters

Basic Configurations available on the marketplace

Datacenter countries available on the marketplace

Hardware specifications available on the marketplace

Practical workflow

The next steps