ThreeFold Marketplace API

Integrate directly with the ThreeFold Marketplace through our REST API.

API Overview

The ThreeFold Marketplace API provides programmatic access to marketplace resources and operations. This allows developers to build applications that interface with the marketplace ecosystem, deploy and manage resources, and perform transactions using TFP.

Base URL

All API requests should be directed to https://api.threefold.pro/v1

Authentication

The API uses token-based authentication. To obtain an API token:

  1. Log in to your ThreeFold Marketplace account
  2. Navigate to Settings > API Access
  3. Generate a new API token with the required scopes
Authentication Example
curl -X GET \
  https://api.threefold.io/v1/resources \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
Security Notice

Keep your API tokens secure. Do not expose them in client-side code or public repositories. Tokens have specific permissions based on the scopes you request.

Resource Endpoints

Compute Resources

Endpoint Method Description
/resources GET List available compute resources
/resources/{id} GET Get details about a specific resource
/resources/search POST Search for resources with specific criteria
/resources/reserve POST Reserve a compute resource
/resources/release/{id} POST Release a reserved compute resource

Deployment

Endpoint Method Description
/deployments GET List all your deployments
/deployments/{id} GET Get details about a specific deployment
/deployments/create POST Create a new deployment
/deployments/{id}/update PUT Update an existing deployment
/deployments/{id}/delete DELETE Delete a deployment

Network Nodes

Endpoint Method Description
/nodes GET List all available nodes
/nodes/{id} GET Get details about a specific node
/nodes/mycelium GET List all Mycelium nodes
/nodes/super GET List all Super nodes
/nodes/register POST Register a new node

TFP Endpoints

Endpoint Method Description
/tfp/balance GET Get your TFP balance
/tfp/transactions GET List your TFP transactions
/tfp/transfer POST Transfer TFP to another account
/tfp/pools GET Get information about available liquidity pools
/tfp/pools/exchange POST Exchange between TFP and other currencies/tokens
/tfp/stake POST Stake TFP

API Response Format

All API responses are returned in JSON format. A typical response includes:

Response Structure
{
  "status": "success", // or "error"
  "data": {
    // Response data specific to the endpoint
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42
    // Additional metadata as needed
  }
}

Error Handling

When an error occurs, the API will return an appropriate HTTP status code and an error message:

Error Response
{
  "status": "error",
  "error": {
    "code": "insufficient_tfp",
    "message": "Insufficient TFP balance for this operation",
    "details": {
      "required": 100,
      "available": 75
    }
  }
}

Rate Limiting

To ensure fair usage of the API, rate limits are applied:

  • Standard accounts: 60 requests per minute
  • Premium accounts: 300 requests per minute

Rate limit information is included in the response headers:

  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in current period
  • X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Sample Code

Node.js Example: Deploy an Application
const axios = require('axios');

const API_TOKEN = 'your_api_token';
const BASE_URL = 'https://api.threefold.pro/v1';

async function deployApplication() {
  try {
    // 1. Find available resources
    const resourceResponse = await axios.post(`${BASE_URL}/resources/search`, {
      cpu_cores: 4,
      memory_mb: 8192,
      disk_gb: 100,
      location: 'europe'
    }, {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    const resourceId = resourceResponse.data.data[0].id;
    
    // 2. Reserve the resource
    await axios.post(`${BASE_URL}/resources/reserve`, {
      resource_id: resourceId,
      duration_hours: 720 // 30 days
    }, {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    // 3. Deploy application
    const deploymentResponse = await axios.post(`${BASE_URL}/deployments/create`, {
      name: 'My Web Application',
      resource_id: resourceId,
      specs: {
        image: 'nginx:latest',
        ports: [80],
        environment: {
          'NGINX_HOST': 'example.org'
        }
      }
    }, {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Deployment successful!', deploymentResponse.data);
    
  } catch (error) {
    console.error('Deployment failed:', error.response?.data || error.message);
  }
}

deployApplication();
Python Example: Deploy an Application
import requests

API_TOKEN = 'your_api_token'
BASE_URL = 'https://api.threefold.pro/v1'

def deploy_application():
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }
    
    try:
        # 1. Find available resources
        resource_response = requests.post(
            f'{BASE_URL}/resources/search',
            json={
                'cpu_cores': 4,
                'memory_mb': 8192,
                'disk_gb': 100,
                'location': 'europe'
            },
            headers=headers
        )
        resource_response.raise_for_status()
        
        resource_id = resource_response.json()['data'][0]['id']
        
        # 2. Reserve the resource
        reserve_response = requests.post(
            f'{BASE_URL}/resources/reserve',
            json={
                'resource_id': resource_id,
                'duration_hours': 720  # 30 days
            },
            headers=headers
        )
        reserve_response.raise_for_status()
        
        # 3. Deploy application
        deployment_response = requests.post(
            f'{BASE_URL}/deployments/create',
            json={
                'name': 'My Web Application',
                'resource_id': resource_id,
                'specs': {
                    'image': 'nginx:latest',
                    'ports': [80],
                    'environment': {
                        'NGINX_HOST': 'example.org'
                    }
                }
            },
            headers=headers
        )
        deployment_response.raise_for_status()
        
        print('Deployment successful!', deployment_response.json())
        
    except requests.exceptions.RequestException as e:
        print(f'Deployment failed: {e}')
        if hasattr(e, 'response') and e.response:
            print(e.response.json())

if __name__ == '__main__':
    deploy_application()
cURL Example: Deploy an Application
# 1. Find available resources
curl -X POST \
  https://api.threefold.pro/v1/resources/search \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpu_cores": 4,
    "memory_mb": 8192,
    "disk_gb": 100,
    "location": "europe"
  }'

# 2. Reserve the resource (replace RESOURCE_ID with actual ID from previous response)
curl -X POST \
  https://api.threefold.pro/v1/resources/reserve \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "RESOURCE_ID",
    "duration_hours": 720
  }'

# 3. Deploy application
curl -X POST \
  https://api.threefold.pro/v1/deployments/create \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Web Application",
    "resource_id": "RESOURCE_ID",
    "specs": {
      "image": "nginx:latest",
      "ports": [80],
      "environment": {
        "NGINX_HOST": "example.org"
      }
    }
  }'
Need More Help?

For additional support or to report API issues, please contact our developer support team at api-support@threefold.pro or visit our GitHub repository.