Skip to main content

Finding Compute Resources on the Fluence Marketplace

The Fluence compute marketplace is a decentralized platform where you can find and rent compute resources from various providers worldwide. Each provider has its own offers in different data centers with different configurations and prices. The marketplace API makes it easy to discover resources that meet your specific requirements.

In this guide, we'll walk through how to:

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

The endpoint to get all available offers on the marketplace is:

POST  [/marketplace/offers](https://api.fluence.dev/marketplace/offers)

Searching 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

Understanding Search 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",
  "additionalResources": {
    "ramMb": 2048,
    "storage": [
      {
        "type": "NVMe",
        "megabytes": 20480
      }
    ]
  },
  "hardware": {
    "cpu": [
      {
        "manufacturer": "AMD",
        "architecture": "Zen" // TODO: add brand and generation
      }
    ],
    "memory": [
      {
        "type": "DDR",
        "generation": "5"
      }
    ],
    "storage": [
      {
        "type": "NVMe"
      }
    ]
  },
  "datacenter": {
    "countries": ["FR"] // TODO: maybe add requirements for data center certifications
  },
  "maxTotalPricePerEpochUsd": "12.57426"
  // TODO: add amount of instances (with additional resources)
}

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 find offers with 8 CPU cores, 16GB RAM, and 25GB storage.

To get the list 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​

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 (object)

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

Example:

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

This filter would find offers with AMD Zen processors, DDR5 memory, and NVMe storage.

Geographic Constraints​

For applications with data residency requirements or to reduce latency for users in specific regions, you can 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"]
  }
}

This filter would find offers with resources located in France or Germany.

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 (object)

    • Additional resources you need beyond the basic configuration.
    • Fields:
      • storage (array of objects)
        • type (string): Type of storage - one of: "HDD", "SSD", or "NVMe"
        • megabytes (integer): Required storage size in megabytes

Example:

{
  "additionalResources": {
    "storage": [
      {
        "type": "NVMe",
        "megabytes": 20480 // TODO: will be supply, units fields instead of megabytes. Change once we have it.
      }
    ]
  }
}

This filter would find offers with 20GB NVMe storage.

Budget Constraint​

You can apply filter for the max price per epoch (24 hours) in USDC that you're willing to pay for the resources. // TODO: specify whether it's per basic configuration or with additional resources.

  • maxTotalPricePerEpochUsd (string)

    • Maximum price you're willing to pay for the resources, in USD. This is expressed as a string to handle decimal precision (e.g. "12.50")

Example:

{
  "maxTotalPricePerEpochUsd": "12.5"
}

This filter would find offers with price per epoch (24 hours) in USDC less than 12.5.

Understanding the Response​

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 identifier for the basic configuration. Read more about basic configurations in the [Basic Configurations section](TODO: put link here). 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 of a configuration object:

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

This object represents a basic configuration with 2 CPU cores, 4GB RAM, and 25GB storage, priced at 0.30698 USDC per epoch.

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](TODO: put link here).
  • price: The price for this resource per epoch

Example of a resources array:

{
  "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:

  • 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 of a datacenter object:

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

This object represents a datacenter in France with the city code PAR (Paris) with Tier 2 and a set of certifications.

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
    • 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 [Resources section](TODO: put link here).
    • price: Cost per unit of this resource

Example of a servers array:

{
  "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
{
  "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:

  1. Price: Different providers set different prices for similar configurations
  2. Location: Same configuration might be available in different datacenters
  3. Hardware specs: CPUs might be from different manufacturers or generations
  4. 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.

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:

{
  "basic_configurations": [
    "cpu-2-ram-4gb-storage-25gb",
    "cpu-4-ram-8gb-storage-25gb",
    "cpu-8-ram-16gb-storage-25gb"
    // More basic configurations
  ]
}

Usage: Use these values in the basicConfiguration field of your offer filters 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 [offer filters](TODO: put link here) 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 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 understand what hardware specifications are available for filtering. You can use these values in the hardware section of your [offer filters](TODO: put link here):

  • 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:

  1. Determine your requirements:
    • Compute power (CPUs, RAM)
    • Storage needs
    • Geographic constraints
    • Budget limitations
  2. 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
  3. Search with filters:
    • Create a filter based on your requirements
    • Send a POST request to /marketplace/offers
  4. Compare and select:
    • Review the returned offers
    • Compare prices, locations, and hardware specs
    • Select the offer that best meets your needs
  5. Proceed to deployment:
    • Use the selected offer to create your deployment

The next steps​

The Fluence compute marketplace API provides a powerful and flexible way to find and compare compute resources from various providers. By using the filtering capabilities and understanding the response structure, you can quickly find resources that match your specific requirements and make informed decisions based on 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.