Getting Started

Chapter 1: Getting Started

Introduction

Welcome to the Polysystems Backend API! This guide will walk you through the initial setup process to start integrating our AI-powered services into your applications.

Prerequisites

Before you begin, ensure you have:

  • A valid email address
  • A secure password (minimum 8 characters recommended)
  • Basic understanding of REST APIs
  • A tool for making HTTP requests (curl, Postman, or your preferred HTTP client)
  • Cryptocurrency wallet (BTC, ETH, or SOL) for adding credits to your account

API Environment

Base URLs

EnvironmentBase URL
Productionhttps://api.polysystems.ai
Developmenthttp://localhost:8080

Supported Authentication Methods

The API supports two authentication methods:

  1. JWT Tokens - For account management and access token generation
  2. Access Tokens (API Keys) - For API endpoint access (recommended for production)

Step 1: Create an Account

Register for a new account using the registration endpoint:

Request

curl -X POST https://api.polysystems.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer1@example.com",
    "password": "YourSecurePassword123!",
    "username": "developer_user1",
    "company_name": "my_company1"
  }'

Response

{
  "user": {
    "id": "40614df7-8a5f-4855-ad17-60c80c30bee3",
    "email": "developer1@example.com",
    "company_name": "my_company1",
    "is_active": true,
    "created_at": "2025-12-24T22:01:44.375461409+00:00"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJlbWFpbCI6ImRldmVsb3BlcjFAZXhhbXBsZS5jb20iLCJjb21wYW55IjoibXlfY29tcGFueTEiLCJleHAiOjE3NjY3MDAxMDQsImlhdCI6MTc2NjYxMzcwNH0.46S4QymoV5gfGD1D9gU2bI603OQel9G_Y54yCenZH30",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc2OTIwNTcwNCwiaWF0IjoxNzY2NjEzNzA0fQ.CS_bSGqvltv-RAxTjuuj2uP2JxcZTj6nBiLz_WZjPYY",
  "token_type": "Bearer",
  "expires_in": 86400
}

Notes

  • Email addresses must be unique
  • Usernames must be unique
  • Password requirements: minimum 8 characters (recommended: use a mix of uppercase, lowercase, numbers, and special characters)
  • Initial account balance: $0.00 USD (you’ll need to add credits to use paid endpoints)

Step 2: Login and Get JWT Token

After registration, login to receive your JWT authentication token:

Request

curl -X POST https://api.polysystems.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer1@example.com",
    "password": "YourSecurePassword123!"
  }'

Response

{
  "user": {
    "id": "40614df7-8a5f-4855-ad17-60c80c30bee3",
    "email": "developer1@example.com",
    "company_name": "my_company1",
    "is_active": true,
    "created_at": "2025-12-24T22:01:44.375461409+00:00"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJlbWFpbCI6ImRldmVsb3BlcjFAZXhhbXBsZS5jb20iLCJjb21wYW55IjoibXlfY29tcGFueTEiLCJleHAiOjE3NjY3MDAxMzcsImlhdCI6MTc2NjYxMzczN30.y7Quxa-ZUF3CbbbFLYoy8mnsLpXM5tWZTFp1qf18pzY",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc2OTIwNTczNywiaWF0IjoxNzY2NjEzNzM3fQ.8ihFL_JXsaNkQFRKKBhTAjOd48XnRzVO65kNPsCfvyk",
  "token_type": "Bearer",
  "expires_in": 86400
}

Important Notes

  • JWT tokens are valid for 24 hours by default
  • Store the token securely (never commit to version control)
  • The JWT token is used for account management operations only
  • For API endpoint access, you’ll generate access tokens (covered in Chapter 3)

Step 3: Check Your Account Balance

Before using paid API endpoints, check your credit balance:

Request

curl -X GET https://api.polysystems.ai/api/payments/credits/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "balance": 0.0,
  "currency": "USD",
  "updated_at": "2025-12-23T20:09:43.997810616+00:00"
}

Step 4: Add Credits to Your Account

To use paid API endpoints, you’ll need to add credits using the x402 payment system. The API supports Bitcoin (BTC), Ethereum (ETH), and Solana (SOL).

Request

curl -X POST https://api.polysystems.ai/api/payments/payments \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJlbWFpbCI6ImRldmVsb3BlcjFAZXhhbXBsZS5jb20iLCJjb21wYW55IjoibXlfY29tcGFueTEiLCJleHAiOjE3NjY3MDAxMzcsImlhdCI6MTc2NjYxMzczN30.y7Quxa-ZUF3CbbbFLYoy8mnsLpXM5tWZTFp1qf18pzY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 1.00,
    "currency": "SOL"
  }'

Response

{
  "id": "35147004-9112-4076-a845-7963cd5abdb5",
  "payment_hash": "x402_54343b0a3d254400a10b1681aefabd49",
  "currency": "SOL",
  "amount_crypto": 0.008130081300813009,
  "amount_usd": 1.0,
  "to_address": "A1eEb71CxTA5tTKX4F31epCVZC4HWhvSXdbETpBSHUWm",
  "status": "pending",
  "confirmations": 0,
  "required_confirmations": 1,
  "tx_hash": null,
  "created_at": "2025-12-24T23:21:14.270866296+00:00",
  "confirmed_at": null,
  "expires_at": "2025-12-25T00:21:14.270866296+00:00"
}

Payment Process

  1. Create Payment Request: Call the payment endpoint to get a payment_id and to_address
  2. Send Cryptocurrency: Send the exact amount_crypto to the provided to_address from your wallet
  3. Confirm Payment: Submit your transaction hash to confirm the payment
  4. Wait for Confirmations: The system verifies the transaction on-chain
  5. Credits Added: Once confirmed, credits are automatically added to your account

Step 4a: Confirm Your Payment

After sending the cryptocurrency, you must confirm the payment by providing your transaction hash:

Request:

curl -X POST https://api.polysystems.ai/api/payments/8e647ebe-767b-4902-84d2-b871dea3fb7c/confirm \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJlbWFpbCI6ImRldmVsb3BlcjFAZXhhbXBsZS5jb20iLCJjb21wYW55IjoibXlfY29tcGFueTEiLCJleHAiOjE3NjY3MDAxMzcsImlhdCI6MTc2NjYxMzczN30.y7Quxa-ZUF3CbbbFLYoy8mnsLpXM5tWZTFp1qf18pzY" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "3MBtKttCgq3aaRPjDv2wEfq5iC91nU1vWeUaGKJaV7zMfMFKTGYcAS3ZPbrBRyoZB2XPQb3BXenp147NBQBxScty",
    "from_address": "ceDgSi6dETUzNBGpP8L2BGeeFXu9NLejHGS7kzMuycA"
  }'

Response:

{
  "id": "8e647ebe-767b-4902-84d2-b871dea3fb7c",
  "payment_hash": "x402_ee168d10660f47e8ae93e264611bd9db",
  "currency": "BTC",
  "amount_crypto": 0.00001140966398539563,
  "amount_usd": 1.0,
  "to_address": "bc1qgm3v7uck5npar0n3qzmvarhkr7pa68emz6s96l",
  "status": "confirming",
  "confirmations": 1,
  "required_confirmations": 3,
  "tx_hash": "YOUR_TRANSACTION_HASH_FROM_WALLET",
  "created_at": "2025-12-24T22:03:46.005880011+00:00",
  "confirmed_at": null,
  "expires_at": "2025-12-24T23:03:46.005880011+00:00"
}

Notes:

  • Replace 8e647ebe-767b-4902-84d2-b871dea3fb7c with your actual payment ID from Step 4
  • Get the tx_hash from your cryptocurrency wallet after sending
  • The from_address is optional but recommended for verification
  • Payment status will change from pending → confirming → confirmed

Step 4b: Check Payment Status

You can check your payment status at any time:

Request:

curl -X GET https://api.polysystems.ai/api/payments/8e647ebe-767b-4902-84d2-b871dea3fb7c \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "id": "8e647ebe-767b-4902-84d2-b871dea3fb7c",
  "status": "confirmed",
  "confirmations": 3,
  "required_confirmations": 3,
  "confirmed_at": "2025-12-24T22:35:12.123456789+00:00"
}

Supported Cryptocurrencies

CurrencyRequired ConfirmationsTypical Confirmation Time
BTC3~30 minutes
ETH12~3 minutes
SOL1~30 seconds

Step 5: Generate Your First Access Token

Access tokens (API keys) are used to authenticate requests to API endpoints. They provide better security and granular control compared to using JWT tokens directly.

Request

curl -X POST https://api.polysystems.ai/api/keys \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDYxNGRmNy04YTVmLTQ4NTUtYWQxNy02MGM4MGMzMGJlZTMiLCJlbWFpbCI6ImRldmVsb3BlcjFAZXhhbXBsZS5jb20iLCJjb21wYW55IjoibXlfY29tcGFueTEiLCJleHAiOjE3NjY3MDAxMzcsImlhdCI6MTc2NjYxMzczN30.y7Quxa-ZUF3CbbbFLYoy8mnsLpXM5tWZTFp1qf18pzY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key"
  }'

Response

{
  "id": "1a35d005-62ce-4e2f-a7d2-712bfe8cf5af",
  "name": "Production API Key",
  "key_value": "ps-key-yh4xbQmTaBs8NOsizgsM2Wsh1P2YCfscO7PBkxHaOobNFfEu",
  "is_active": true,
  "created_at": "2025-12-24T23:31:52.945121690+00:00",
  "expires_at": null
}

Important

  • Save the key_value immediately - it’s only shown once during creation
  • Access tokens can be revoked or deleted at any time
  • You can create multiple access tokens for different applications or environments
  • See Chapter 3: Access Tokens for detailed management options

Step 6: Make Your First API Call

Now you’re ready to make your first API call using your access token:

Request

curl -X GET https://api.polysystems.ai/api/hub/health \
  -H "X-API-Key: ps_live_abcdefghijklmnopqrstuvwxyz123456789"

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:45:00Z"
}

Using Access Tokens

Access tokens can be provided in two ways:

Method 1: X-API-Key Header (Recommended)

curl -H "X-API-Key: YOUR_ACCESS_TOKEN" https://api.polysystems.ai/api/endpoint

Method 2: Authorization Bearer Header

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.polysystems.ai/api/endpoint

Development Workflow

Here’s a typical development workflow:

1. Register Account → 2. Login (Get JWT) → 3. Add Credits
                                ↓
4. Generate Access Token → 5. Set Spending Limits (Optional)
                                ↓
6. Configure Webhooks (Optional) → 7. Start Making API Calls
                                ↓
8. Monitor Usage → 9. Manage Access Tokens → 10. Top Up Credits

Testing Your Integration

Health Check Endpoints

Test your setup with these public health check endpoints:

# Hub Health Check
curl https://api.polysystems.ai/api/hub/health
 
# OMM Health Check
curl https://api.polysystems.ai/api/omm/health

Example Protected Endpoint

curl -X POST https://api.polysystems.ai/api/hub/agents/chat \
  -H "X-API-Key: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello, World!"}
    ],
    "model": "gpt-4",
    "temperature": 0.7
  }'

Environment Variables

For security, store your credentials as environment variables:

Bash/Zsh

export PS_JWT_TOKEN="your_jwt_token_here"
export PS_API_KEY="your_access_token_here"

Usage in Requests

curl -H "X-API-Key: $PS_API_KEY" https://api.polysystems.ai/api/endpoint

.env File (for applications)

PS_API_URL=https://api.polysystems.ai
PS_API_KEY=ps_live_your_access_token_here
PS_JWT_TOKEN=your_jwt_token_here

⚠️ Important: Never commit .env files or tokens to version control. Add .env to your .gitignore file.

Common Setup Issues

Issue: “Invalid credentials” on login

Solution: Verify your email and password are correct. Passwords are case-sensitive.

Issue: “Insufficient credits” error

Solution: Add credits to your account via the x402 payment system. See Step 4 above.

Issue: “Invalid API key” error

Solution:

  • Ensure you’re using the correct access token
  • Check if the token is still active (is_active: true)
  • Verify the token hasn’t expired
  • Confirm you’re using the correct header format

Issue: “Rate limit exceeded”

Solution: You’ve exceeded the rate limit. Wait for the rate limit window to reset or upgrade your plan.

Issue: Payment not confirmed

Solution:

  • Ensure you called the /confirm endpoint with your transaction hash
  • Verify you sent the exact crypto amount to the correct address
  • Wait for blockchain confirmations (timing varies by currency)
  • Check payment status using the payment ID
  • For testing/development: You may need to manually update the database if blockchain verification fails

Next Steps

Now that your account is set up and you’ve made your first API call, continue to:

Summary

In this chapter, you learned how to:

  • ✅ Create an account
  • ✅ Login and obtain JWT tokens
  • ✅ Add credits using cryptocurrency
  • ✅ Generate access tokens
  • ✅ Make your first API call
  • ✅ Store credentials securely

You’re now ready to integrate the Polysystems API into your applications!

IntroductionAuthentication