API Reference

The STAB3L API provides programmatic access to the STAB3L platform, allowing developers to integrate compute unit standardization, verification, and marketplace functionality into their applications.

{% hint style="info" %} The API is available at https://api.stab3l.com. All requests must use HTTPS. {% endhint %}

Authentication

The STAB3L API uses JWT (JSON Web Tokens) for authentication:

Obtaining an API Key

1. Register or log in to the STAB3L Developer Portal
2. Navigate to the "API Keys" section
3. Create a new API key
4. Store your API key securely

Authentication Methods

{% tabs %} {% tab title="Bearer Token" %} Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example:

curl -X GET \
  https://api.stab3l.com/api/v1/cu/list \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{% endtab %}

{% tab title="Query Parameter" %} Include your API key as a query parameter:

?api_key=YOUR_API_KEY

Example:

curl -X GET \
  'https://api.stab3l.com/api/v1/cu/list?api_key=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{% hint style="warning" %} This method is less secure and should only be used for testing. {% endhint %} {% endtab %}

{% tab title="SDK Authentication" %} When using the STAB3L SDK, initialize it with your API key:

// JavaScript SDK
const stab3l = require('stab3l-sdk');

// Initialize with API key
const client = new stab3l.Client({
  apiKey: 'YOUR_API_KEY'
});

// Make authenticated requests
const cuList = await client.cu.list();

# Python SDK
import stab3l

# Initialize with API key
client = stab3l.Client(api_key='YOUR_API_KEY')

# Make authenticated requests
cu_list = client.cu.list()

{% endtab %} {% endtabs %}

Rate Limiting

The API implements rate limiting to ensure fair usage:

• Standard Tier: 100 requests per minute
• Premium Tier: 500 requests per minute
• Enterprise Tier: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

API Endpoints

Compute Units

{% hint style="warning" %} Important: CU tokens are NOT tradable assets. They are temporary tokens that are burned immediately when exchanged for sSTB. This burning mechanism is crucial for maintaining the peg and ensuring that each sSTB is backed by real compute resources. {% endhint %}

List Verified Compute Units

GET /api/v1/cu/list

Returns a list of verified compute units based on the specified filters.

Parameters:

Response:

{
  "success": true,
  "data": {
    "compute_units": [
      {
        "cu_id": 123,
        "cu_hash": "0x... (PLACEHOLDER)",
        "cu_value": 100,
        "provider_id": "provider-123",
        "verification_timestamp": 1640995200,
        "metadata": {
          "cpu_cores": 8,
          "ram_gb": 32,
          "storage_gb": 500,
          "network_mbps": 1000
        }
      }
    ],
    "total": 150,
    "page": 1,
    "limit": 20
  }
}

Get Compute Unit Details

GET /api/v1/cu/:cu_id

Returns detailed information about a specific verified compute unit.

Parameters:

Response:

{
  "success": true,
  "data": {
    "cu_id": 123,
    "cu_hash": "0x... (PLACEHOLDER)",
    "cu_value": 100,
    "provider_id": "provider-123",
    "verification_timestamp": 1640995200,
    "owner": "0x... (PLACEHOLDER)",
    "metadata": {
      "cpu_cores": 8,
      "ram_gb": 32,
      "storage_gb": 500,
      "network_mbps": 1000,
      "location": {
        "country": "United States",
        "region": "US-East"
      },
      "benchmark_results": {
        "cpu_score": 8500,
        "memory_score": 7800,
        "storage_score": 9200,
        "network_score": 8900
      }
    }
  }
}

Providers

List Providers

GET /api/v1/providers/list

Returns a list of registered compute providers.

Parameters:

Response:

{
  "success": true,
  "data": {
    "providers": [
      {
        "provider_id": "provider-123",
        "name": "Example Provider",
        "status": "active",
        "reputation_score": 95,
        "location": {
          "country": "United States",
          "region": "US-East"
        },
        "total_cu_value": 10000,
        "available_cu_value": 5000
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20
  }
}

Get Provider Details

GET /api/v1/providers/:provider_id

Returns detailed information about a specific provider.

Parameters:

Response:

{
  "success": true,
  "data": {
    "provider_id": "provider-123",
    "name": "Example Provider",
    "status": "active",
    "reputation_score": 95,
    "registration_date": 1640995200,
    "location": {
      "country": "United States",
      "region": "US-East"
    },
    "contact_info": {
      "email": "provider@example.com",
      "website": "https://example.com"
    },
    "hardware_specifications": {
      "cpu_type": "AMD EPYC 7763",
      "total_cpu_cores": 512,
      "total_ram_gb": 4096,
      "total_storage_gb": 100000,
      "network_capacity_mbps": 10000
    },
    "statistics": {
      "total_cu_value": 10000,
      "available_cu_value": 5000,
      "total_redemptions": 150,
      "successful_redemptions": 148,
      "average_response_time": 15 // minutes
    }
  }
}

Marketplace

List sSTB Marketplace Listings

GET /api/v1/marketplace/listings

Returns a list of active marketplace listings for sSTB tokens.

Parameters:

Response:

{
  "success": true,
  "data": {
    "listings": [
      {
        "listing_id": 456,
        "market_type": "spot",
        "token_type": "sSTB",
        "seller": "0x... (PLACEHOLDER)",
        "amount": 10,
        "price_per_token": 0.06,
        "total_price": 0.6,
        "listed_at": 1640995200,
        "expiration": 1672531200
      }
    ],
    "total": 200,
    "page": 1,
    "limit": 20
  }
}

Get Listing Details

GET /api/v1/marketplace/listings/:listing_id

Returns detailed information about a specific marketplace listing.

Parameters:

Response:

{
  "success": true,
  "data": {
    "listing_id": 456,
    "token_type": "sSTB",
    "amount": 10,
    "price_per_token": 0.06,
    "seller": "0x... (PLACEHOLDER)",
    "created_at": 1640995200,
    "status": "active"
  }
}

Bridge

List Supported Chains

GET /api/v1/bridge/chains

Returns a list of chains supported by the bridge.

Response:

{
  "success": true,
  "data": {
    "chains": [
      {
        "chain_id": "arbitrum",
        "name": "Arbitrum",
        "native_chain_id": 42161,
        "is_evm_compatible": true,
        "bridge_address": "0x... (PLACEHOLDER)",
        "status": "active"
      },
      {
        "chain_id": "ethereum",
        "name": "Ethereum",
        "native_chain_id": 1,
        "is_evm_compatible": true,
        "bridge_address": "0x... (PLACEHOLDER)",
        "status": "active"
      }
    ]
  }
}

Get Bridge Fees

GET /api/v1/bridge/fees

Returns the current bridge fees for different chains and fee tokens.

Parameters:

Response:

{
  "success": true,
  "data": {
    "source_chain": "arbitrum",
    "destination_chain": "ethereum",
    "amount": 10,
    "fees": {
      "default": {
        "token": "USDC",
        "amount": 5.00
      },
      "stab3l": {
        "token": "STAB3L",
        "amount": 50.00,
        "discount": "10%"
      },
      "stb_gov": {
        "token": "STB-GOV",
        "amount": 2.50,
        "discount": "25%"
      }
    }
  }
}

Get Bridge Transaction Status

GET /api/v1/bridge/status/:message_id

Returns the status of a bridge transaction.

Parameters:

Response:

{
  "success": true,
  "data": {
    "message_id": "msg-123",
    "source_chain": "arbitrum",
    "destination_chain": "polygon",
    "token": "sSTB",
    "amount": 10,
    "sender": "0x... (PLACEHOLDER)",
    "recipient": "0x... (PLACEHOLDER)",
    "status": "completed",
    "created_at": 1640995200,
    "completed_at": 1640995500,
    "source_transaction": "0x... (PLACEHOLDER)",
    "destination_transaction": "0x... (PLACEHOLDER)"
  }
}

Verification

Submit Verification

POST /api/v1/verification/submit

Submits compute resources for verification.

Request Body:

{
  "verification_type": "zkp",
  "provider_id": "provider-123",
  "benchmark_results": {
    "cpu_score": 8500,
    "memory_score": 7800,
    "storage_score": 9200,
    "network_score": 8900
  },
  "proof": "0x... (PLACEHOLDER)",
  "metadata": {
    "cpu_cores": 8,
    "ram_gb": 32,
    "storage_gb": 500,
    "network_mbps": 1000
  }
}

Response:

{
  "success": true,
  "data": {
    "verification_id": "ver-123",
    "status": "verified",
    "created_at": 1640995200,
    "verified_at": 1640995500
  }
}

Check Verification Status

GET /api/v1/verification/:verification_id

Checks the status of a verification request.

Parameters:

Response:

{
  "success": true,
  "data": {
    "verification_id": "ver-123",
    "provider_id": "provider-123",
    "verification_method": "zkp",
    "proof": "0x... (PLACEHOLDER)",
    "status": "verified",
    "created_at": 1640995200,
    "verified_at": 1640995500
  }
}

Redemptions

Initiate Redemption

POST /api/v1/redemptions

Initiates a redemption of sSTB tokens for compute resources.

Request Body:

{
  "sstb_amount": 100,
  "provider_id": "provider-123",
  "specifications": {
    "cpu_cores": 8,
    "ram_gb": 32,
    "storage_gb": 500,
    "network_mbps": 1000
  }
}

Response:

{
  "success": true,
  "data": {
    "redemption_id": "redemption-123",
    "status": "pending",
    "sstb_amount": 100,
    "provider_id": "provider-123",
    "initiated_at": 1640995200,
    "estimated_fulfillment_time": 1640998800
  }
}

Webhooks

The STAB3L API supports webhooks for real-time notifications:

Setting Up Webhooks

1. Navigate to the "Webhooks" section in the Developer Portal
2. Add a new webhook URL
3. Select the events you want to subscribe to
4. Configure optional security settings

Webhook Events

Webhook Payload

{
  "event": "sstb.minted",
  "timestamp": 1640995200,
  "data": {
    "provider_id": "provider-123",
    "cu_value": 100,
    "sstb_amount": 100,
    "owner": "0x... (PLACEHOLDER)"
  }
}

Webhook Security

To ensure webhook security:

1. Verify the signature in the X-STAB3L-Signature header
2. Use HTTPS for your webhook endpoint
3. Implement retry logic for failed webhook deliveries

Error Handling

The API uses standard HTTP status codes and returns detailed error information:

{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "The provided parameter is invalid",
    "details": {
      "parameter": "provider_id",
      "reason": "Provider ID does not exist"
    }
  }
}

Common Error Codes

SDKs and Libraries

STAB3L provides official SDKs for popular programming languages:

Best Practices

{% hint style="success" %} Following these best practices will help you build robust applications with the STAB3L API. {% endhint %}

Performance Optimization

1. Use Pagination: Always use pagination for list endpoints
2. Limit Response Fields: Request only the fields you need
3. Cache Responses: Cache responses that don't change frequently
4. Use Webhooks: Use webhooks for real-time updates instead of polling

Security

1. Secure API Keys: Store API keys securely and never expose them in client-side code
2. Use HTTPS: Always use HTTPS for API requests
3. Implement Rate Limiting: Add rate limiting in your application
4. Validate Webhook Signatures: Always validate webhook signatures

Error Handling

1. Implement Retry Logic: Retry failed requests with exponential backoff
2. Handle Rate Limits: Respect rate limit headers and pause requests when limits are reached
3. Log Errors: Log detailed error information for debugging
4. Graceful Degradation: Design your application to gracefully handle API unavailability

Conclusion

The STAB3L API provides comprehensive access to the platform's functionality, enabling developers to build applications that leverage compute unit standardization, verification, and marketplace features. For additional support, visit the Developer Forum or contact developer support.