OASIS Provider Architecture

For External Developers Building Interoperable Systems

Version: 2.0 Date: November 6, 2025 Audience: Third-party developers integrating with OASIS Purpose: Complete guide to building applications using OASIS's multi-provider architecture

What is the OASIS Provider Architecture?

Overview

OASIS is a universal data layer that lets you interact with 30+ blockchains, databases, and storage systems through a single, unified API. Instead of learning and integrating with each blockchain separately, you make one API call and OASIS handles the multi-chain complexity for you.

Currently Active: 15 fully configured providers Built & Available: 34 providers ready to activate Roadmap: 50+ providers planned

Key Concept: "Write Once, Store Everywhere"

Your Application
      ↓
  OASIS API (Single Call)
      ↓
OASIS HyperDrive (Automatic Distribution)
      ↓
┌────────────────────────────────────────────────┐
│ Ethereum  Solana  MongoDB  IPFS  Polygon  ... │
└────────────────────────────────────────────────┘
All configured providers updated automatically

Traditional approach:

Write integration for Ethereum
Write separate integration for Solana
Write separate integration for Polygon
... (months of work)

OASIS approach:

Write one integration with OASIS
Works with all 50+ providers automatically
... (hours of work)

How It Works

The Core Mechanism: HyperDrive

HyperDrive is OASIS's intelligent orchestration layer with three key features:

1. Auto-Replication

When you save data, it automatically replicates to multiple providers:

You: Save avatar profile
      ↓
OASIS: Saves to MongoDB (fast, primary)
       Saves to IPFS (permanent backup)
       Saves to Ethereum (on-chain proof)
       Saves to Arbitrum (backup blockchain)

Configuration:

{
  "AutoReplicationEnabled": true,
  "AutoReplicationProviders": "MongoDBOASIS, IPFSOASIS, ArbitrumOASIS"
}

2. Auto-Failover

If one provider fails, OASIS automatically tries the next:

You: Request user data
      ↓
OASIS: Try MongoDB → TIMEOUT (failed)
       Try Arbitrum → SUCCESS
       Return data (user never knew MongoDB failed)

Configuration:

{
  "AutoFailOverEnabled": true,
  "AutoFailOverProviders": "MongoDBOASIS, ArbitrumOASIS, EthereumOASIS"
}

Result: 100% uptime - Your app keeps working even if 10+ providers go down.

3. Auto-Load Balancing

Distributes requests across providers for optimal performance:

Request 1 → MongoDB (fast, 50ms)
Request 2 → Arbitrum (medium, 900ms)
Request 3 → IPFS (slow, 2000ms)
Request 4 → MongoDB (back to fastest)

Configuration:

{
  "AutoLoadBalanceEnabled": true,
  "AutoLoadBalanceProviders": "MongoDBOASIS, ArbitrumOASIS"
}

Available Providers

OASIS has 34 built providers with 15 currently active and configured:

✅ Currently Active & Configured

These providers are ready to use RIGHT NOW:

Blockchains (7):

SolanaOASIS ✓ - Solana (mainnet configured)
EthereumOASIS ✓ - Ethereum (Sepolia testnet)
ArbitrumOASIS ✓ - Arbitrum (Sepolia testnet)
PolygonOASIS ✓ - Polygon (Amoy testnet)
RootstockOASIS ✓ - Rootstock (testnet)
TelosOASIS ✓ - Telos
SEEDSOASIS ✓ - Seeds/Hypha

Databases (3):

MongoDBOASIS ✓ - MongoDB (primary, fully configured)
SQLLiteDBOASIS ✓ - SQLite
Neo4jOASIS ⚠️ - Neo4j (needs password configuration)

Storage (3):

PinataOASIS ✓ - Pinata (IPFS gateway, fully configured)
LocalFileOASIS ✓ - Local file storage
IPFSOASIS ⚠️ - IPFS (needs configuration)

Other (2):

HoloOASIS ⚠️ - Holochain (localhost only)
TelegramOASIS ✓ - Telegram integration

🔧 Built But Needs Configuration

These providers exist but need API keys/setup:

Blockchain Providers (30+)

EVM Compatible:

EthereumOASIS - Ethereum mainnet/testnets
PolygonOASIS - Polygon PoS
ArbitrumOASIS - Arbitrum L2
BaseOASIS - Base (Coinbase L2)
MonadOASIS - Monad high-throughput L1 (EVM-equivalent)
TONOASIS - TON EVM gateway
OptimismOASIS - Optimism L2
AvalancheOASIS - Avalanche C-Chain
FantomOASIS - Fantom Opera
BNBOASIS - BNB Chain (BSC)
RootstockOASIS - Rootstock (Bitcoin L2)

Non-EVM:

SolanaOASIS - Solana
EOSIOOASIS - EOSIO
TelosOASIS - Telos
SEEDSOASIS - Seeds/Hypha
CardanoOASIS - Cardano (planned)
PolkadotOASIS - Polkadot (planned)
CosmosOASIS - Cosmos (planned)
NEAROASIS - NEAR Protocol (planned)
SuiOASIS - Sui (planned)
AptosOASIS - Aptos (planned)

Other:

HoloOASIS - Holochain
HashgraphOASIS - Hedera Hashgraph
StellarOASIS - Stellar
TRONOASIS - Tron
ElrondOASIS - MultiversX

Database Providers (10+)

MongoDBOASIS - MongoDB (primary)
Neo4jOASIS - Neo4j graph database
SQLLiteDBOASIS - SQLite
SQLServerDBOASIS - Microsoft SQL Server
PostgreSQLOASIS - PostgreSQL (planned)
OracleDBOASIS - Oracle Database (planned)
AzureCosmosDBOASIS - Azure Cosmos DB

Storage Providers (5+)

IPFSOASIS - IPFS (InterPlanetary File System)
PinataOASIS - Pinata (IPFS gateway)
ArweaveOASIS - Arweave (permanent storage, planned)
LocalFileOASIS - Local file storage
AWSOASIS - Amazon S3
AzureStorageOASIS - Azure Blob Storage
GoogleCloudOASIS - Google Cloud Storage

Network Providers (5+)

ActivityPubOASIS - ActivityPub (Mastodon, etc.)
ScuttlebuttOASIS - Scuttlebutt
SOLIDOASIS - Solid protocol
ThreeFoldOASIS - ThreeFold Network

TelegramOASIS - Telegram integration
TwitterOASIS - Twitter/X (planned)
DiscordOASIS - Discord (planned)

Getting Started

Step 1: Get API Access

Option A: Use Public OASIS API

Base URL: https://api.oasisweb4.one

Option B: Self-Host OASIS

git clone https://github.com/NextGenSoftwareUK/OASIS.git
cd OASIS
dotnet run --project ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI

Local URL: https://localhost:5002

Step 2: Create an Avatar (User Account)

Every interaction requires an Avatar ID. Think of it as your universal user account across all providers.

Endpoint: POST /api/avatar/register

Request:

curl -X POST "https://api.oasisweb4.one/api/avatar/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myapp_user",
    "email": "user@myapp.com",
    "password": "securePassword123",
    "firstName": "John",
    "lastName": "Doe",
    "avatarType": "User",
    "acceptTerms": true
  }'

Response:

{
  "success": true,
  "avatar": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "username": "myapp_user",
    "email": "user@myapp.com"
  },
  "jwtToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Save these:

avatar.id - You'll use this in all subsequent calls
jwtToken - For authentication (expires in 24 hours)

Step 3: Authenticate

For subsequent sessions, authenticate to get a new token:

Endpoint: POST /api/avatar/authenticate

curl -X POST "https://api.oasisweb4.one/api/avatar/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myapp_user",
    "password": "securePassword123"
  }'

API Endpoints

Core Pattern: Provider-Agnostic Operations

All data operations follow the same pattern and work across ALL providers:

Save Data (with Auto-Replication)

Endpoint: POST /api/data/save-holon

What is a Holon? A universal data structure that can store anything (user profiles, game state, NFT metadata, etc.)

curl -X POST "https://api.oasisweb4.one/api/data/save-holon" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "UserProfile_123",
    "description": "User profile data",
    "holonType": "UserProfile",
    "metadata": {
      "userId": "123",
      "preferences": {
        "theme": "dark",
        "notifications": true
      },
      "gameProgress": {
        "level": 42,
        "xp": 15000
      }
    }
  }'

Response:

{
  "result": {
    "id": "holon-uuid-here",
    "name": "UserProfile_123",
    "savedToProviders": [
      "MongoDBOASIS",
      "IPFSOASIS",
      "ArbitrumOASIS"
    ],
    "saveTime": "2025-11-06T10:30:00Z"
  },
  "isError": false,
  "message": "Saved to 3 providers"
}

What just happened:

Your data was automatically saved to MongoDB (fast database)
Backed up to IPFS (permanent storage)
Written to Arbitrum blockchain (immutable proof)
All in one API call

Load Data (with Auto-Failover)

Endpoint: GET /api/data/load-holon/{holonId}

curl -X GET "https://api.oasisweb4.one/api/data/load-holon/holon-uuid-here" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

What happens behind the scenes:

OASIS tries MongoDB first (fastest)
If MongoDB is down, tries Arbitrum
If Arbitrum is down, tries IPFS
Returns data from first available provider
You get your data regardless of which provider is working

Specify Specific Provider (Optional)

If you want to use a specific provider:

Endpoint: GET /api/data/load-holon/{holonId}/{providerType}/{setGlobally}

curl -X GET "https://api.oasisweb4.one/api/data/load-holon/holon-uuid-here/SolanaOASIS/false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This forces loading from Solana, but if it fails, auto-failover kicks in.

Code Examples

JavaScript/TypeScript Example

// oasis-client.ts
class OASISClient {
  private baseUrl = 'https://api.oasisweb4.one';
  private jwtToken: string;
  
  constructor(jwtToken: string) {
    this.jwtToken = jwtToken;
  }
  
  // Save data to all configured providers
  async saveData(data: any): Promise<any> {
    const response = await fetch(`${this.baseUrl}/api/data/save-holon`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.jwtToken}`
      },
      body: JSON.stringify({
        name: `${data.type}_${data.id}`,
        description: data.description,
        holonType: data.type,
        metadata: data
      })
    });
    
    return await response.json();
  }
  
  // Load data with automatic failover
  async loadData(holonId: string): Promise<any> {
    const response = await fetch(
      `${this.baseUrl}/api/data/load-holon/${holonId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwtToken}`
        }
      }
    );
    
    const result = await response.json();
    return result.result?.metadata;
  }
  
  // Save to specific blockchain
  async saveToBlockchain(data: any, blockchain: string): Promise<any> {
    const response = await fetch(
      `${this.baseUrl}/api/data/save-holon/${blockchain}/false`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.jwtToken}`
        },
        body: JSON.stringify({
          name: `${data.type}_${data.id}`,
          holonType: data.type,
          metadata: data
        })
      }
    );
    
    return await response.json();
  }
}

// Usage Example
async function main() {
  // 1. Authenticate
  const authResponse = await fetch(
    'https://api.oasisweb4.one/api/avatar/authenticate',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        username: 'myapp_user',
        password: 'mypassword'
      })
    }
  );
  
  const auth = await authResponse.json();
  const token = auth.result.data.token;
  
  // 2. Create OASIS client
  const oasis = new OASISClient(token);
  
  // 3. Save user data - goes to ALL configured providers
  const saveResult = await oasis.saveData({
    type: 'UserProfile',
    id: 'user123',
    name: 'Alice',
    email: 'alice@example.com',
    preferences: {
      theme: 'dark',
      notifications: true
    }
  });
  
  console.log('Saved to providers:', saveResult.result.savedToProviders);
  // Output: ["MongoDBOASIS", "IPFSOASIS", "ArbitrumOASIS"]
  
  // 4. Load data - auto-failover if MongoDB down
  const userData = await oasis.loadData(saveResult.result.id);
  console.log('User data:', userData);
  
  // 5. Save specifically to Solana
  const solanaResult = await oasis.saveToBlockchain(userData, 'SolanaOASIS');
  console.log('Saved to Solana:', solanaResult);
}

Python Example

import requests

class OASISClient:
    def __init__(self, jwt_token):
        self.base_url = 'https://api.oasisweb4.one'
        self.token = jwt_token
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {jwt_token}'
        }
    
    def save_data(self, data):
        """Save data to all configured providers"""
        payload = {
            'name': f"{data['type']}_{data['id']}",
            'description': data.get('description', ''),
            'holonType': data['type'],
            'metadata': data
        }
        
        response = requests.post(
            f'{self.base_url}/api/data/save-holon',
            json=payload,
            headers=self.headers
        )
        
        return response.json()
    
    def load_data(self, holon_id):
        """Load data with automatic failover"""
        response = requests.get(
            f'{self.base_url}/api/data/load-holon/{holon_id}',
            headers=self.headers
        )
        
        result = response.json()
        return result['result']['metadata']

# Usage
def main():
    # 1. Authenticate
    auth_response = requests.post(
        'https://api.oasisweb4.one/api/avatar/authenticate',
        json={
            'username': 'myapp_user',
            'password': 'mypassword'
        }
    )
    
    token = auth_response.json()['result']['data']['token']
    
    # 2. Create client
    oasis = OASISClient(token)
    
    # 3. Save data
    result = oasis.save_data({
        'type': 'UserProfile',
        'id': 'user123',
        'name': 'Alice',
        'email': 'alice@example.com'
    })
    
    print(f"Saved to: {result['result']['savedToProviders']}")
    
    # 4. Load data
    user_data = oasis.load_data(result['result']['id'])
    print(f"Loaded data: {user_data}")

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class OASISClient
{
    private readonly HttpClient _client;
    private readonly string _baseUrl = "https://api.oasisweb4.one";
    
    public OASISClient(string jwtToken)
    {
        _client = new HttpClient();
        _client.DefaultRequestHeaders.Add("Authorization", $"Bearer {jwtToken}");
    }
    
    // Save data to all providers
    public async Task<object> SaveData(object data)
    {
        var holon = new
        {
            name = $"{data.GetType().Name}_{Guid.NewGuid()}",
            holonType = data.GetType().Name,
            metadata = data
        };
        
        var json = JsonSerializer.Serialize(holon);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _client.PostAsync(
            $"{_baseUrl}/api/data/save-holon",
            content
        );
        
        return JsonSerializer.Deserialize<object>(
            await response.Content.ReadAsStringAsync()
        );
    }
    
    // Load data with failover
    public async Task<T> LoadData<T>(string holonId)
    {
        var response = await _client.GetAsync(
            $"{_baseUrl}/api/data/load-holon/{holonId}"
        );
        
        var result = JsonSerializer.Deserialize<dynamic>(
            await response.Content.ReadAsStringAsync()
        );
        
        return JsonSerializer.Deserialize<T>(
            result.result.metadata.ToString()
        );
    }
}

// Usage
public class Program
{
    public static async Task Main()
    {
        // 1. Authenticate
        var authClient = new HttpClient();
        var authContent = new StringContent(
            JsonSerializer.Serialize(new { 
                username = "myapp_user", 
                password = "mypassword" 
            }),
            Encoding.UTF8,
            "application/json"
        );
        
        var authResponse = await authClient.PostAsync(
            "https://api.oasisweb4.one/api/avatar/authenticate",
            authContent
        );
        
        var authData = JsonSerializer.Deserialize<dynamic>(
            await authResponse.Content.ReadAsStringAsync()
        );
        
        var token = authData.result.data.token.ToString();
        
        // 2. Create OASIS client
        var oasis = new OASISClient(token);
        
        // 3. Save data
        var userData = new {
            type = "UserProfile",
            id = "user123",
            name = "Alice",
            email = "alice@example.com"
        };
        
        var saveResult = await oasis.SaveData(userData);
        Console.WriteLine($"Saved to providers: {saveResult}");
        
        // 4. Load data
        var loadedData = await oasis.LoadData<dynamic>(holonId);
        Console.WriteLine($"Loaded data: {loadedData}");
    }
}

Advanced Features

Multi-Chain Wallets

Generate wallets for your users on ALL blockchains with one API call:

Endpoint: POST /api/wallet/avatar/{avatarId}/generate

curl -X POST "https://api.oasisweb4.one/api/wallet/avatar/YOUR_AVATAR_ID/generate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "SolanaOASIS",
    "setAsDefault": true
  }'

Response:

{
  "result": {
    "walletId": "wallet-uuid",
    "publicKey": "AfpSpMjNyoHTZWMWkog6Znf57KV82MGzkpDUUjLtmHwG",
    "providerType": "SolanaOASIS",
    "balance": 0
  }
}

Generate for ALL chains:

const chains = [
  'SolanaOASIS',
  'EthereumOASIS',
  'PolygonOASIS',
  'ArbitrumOASIS',
  'BaseOASIS'
];

for (const chain of chains) {
  await fetch(
    `https://api.oasisweb4.one/api/wallet/avatar/${avatarId}/generate`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        providerType: chain,
        setAsDefault: chain === 'SolanaOASIS'
      })
    }
  );
}

// User now has wallets on ALL 5 chains, managed by OASIS

Cross-Chain NFTs

Mint NFTs that exist on multiple chains:

Endpoint: POST /api/nft/mint

curl -X POST "https://api.oasisweb4.one/api/nft/mint" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "avatarId": "YOUR_AVATAR_ID",
    "name": "My Cool NFT",
    "description": "This NFT exists on multiple chains",
    "imageUrl": "ipfs://QmX...",
    "metadata": {
      "attributes": [
        {"trait_type": "Rarity", "value": "Legendary"}
      ]
    },
    "mintToProviders": [
      "ArbitrumOASIS",
      "PolygonOASIS",
      "IPFSOASIS"
    ]
  }'

Response:

{
  "result": {
    "nftId": "nft-uuid",
    "mintedOnChains": [
      {
        "provider": "ArbitrumOASIS",
        "tokenId": "12345",
        "contractAddress": "0xABC..."
      },
      {
        "provider": "PolygonOASIS",
        "tokenId": "67890",
        "contractAddress": "0xDEF..."
      }
    ],
    "metadataUrl": "ipfs://QmX..."
  }
}

Provider Health Monitoring

Check which providers are currently available:

Endpoint: GET /api/provider/health

curl -X GET "https://api.oasisweb4.one/api/provider/health" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "providers": [
    {
      "name": "MongoDBOASIS",
      "status": "online",
      "latency": "45ms",
      "lastCheck": "2025-11-06T10:30:00Z"
    },
    {
      "name": "SolanaOASIS",
      "status": "online",
      "latency": "400ms"
    },
    {
      "name": "EthereumOASIS",
      "status": "degraded",
      "latency": "15000ms",
      "warning": "High latency detected"
    }
  ],
  "healthyCount": 48,
  "totalCount": 50
}

Use Cases for Your Application

Use Case 1: Multi-Chain Game

Problem: You're building a game where players should be able to play on any blockchain

Solution with OASIS:

// Save player progress
await oasis.saveData({
  type: 'GameProgress',
  playerId: 'player123',
  level: 42,
  inventory: [...],
  achievements: [...]
});

// Player can now:
// - Login from Ethereum wallet → sees their progress
// - Switch to Solana wallet → sees SAME progress
// - Play on Polygon → progress synced everywhere

// You don't care which blockchain they use - OASIS handles it

Problem: Users on different blockchains can't interact

Solution with OASIS:

// Create user profile (saved to all chains)
await oasis.saveData({
  type: 'UserProfile',
  username: 'alice',
  bio: 'Web3 enthusiast',
  followers: []
});

// Alice on Ethereum follows Bob on Solana
// - Works seamlessly because both profiles exist everywhere
// - No bridge needed
// - Instant cross-chain social graph

Use Case 3: Cross-Chain Marketplace

Problem: NFT sellers on Ethereum, buyers on Solana - they can't trade

Solution with OASIS:

// List NFT for sale (saved to all providers)
await oasis.saveData({
  type: 'MarketplaceListing',
  nftId: 'nft123',
  seller: 'alice',
  sellerChain: 'EthereumOASIS',
  price: 100,
  acceptedPaymentChains: [
    'SolanaOASIS',
    'PolygonOASIS',
    'ArbitrumOASIS'
  ]
});

// Buyer on Solana can see it immediately
// Payment happens on Solana
// OASIS orchestrates the cross-chain settlement
// NFT transferred to buyer on their preferred chain

Advanced Features

1. Provider Selection Strategy

Configure how OASIS chooses providers:

// Save to fastest provider first, then replicate
const result = await fetch(
  'https://api.oasisweb4.one/api/data/save-holon',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...holonData,
      options: {
        strategy: 'FASTEST_FIRST',  // Other: CHEAPEST, MOST_RELIABLE
        replicationMode: 'ASYNC',   // Replicate in background
        minimumProviders: 3,         // Must save to at least 3
        requiredProviders: ['MongoDBOASIS']  // Must include MongoDB
      }
    })
  }
);

2. Conflict Resolution

If data diverges across providers (rare, but possible):

// Load with consensus check
const result = await fetch(
  `https://api.oasisweb4.one/api/data/load-holon-with-consensus/${holonId}`,
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);

const data = await result.json();

console.log(data.result);
// {
//   data: {...},
//   consensus: {
//     agreement: "90%",
//     providers: {
//       "MongoDBOASIS": { version: "v1", hash: "0xABC..." },
//       "ArbitrumOASIS": { version: "v1", hash: "0xABC..." },
//       "IPFSOASIS": { version: "v1", hash: "0xABC..." },
//       "EthereumOASIS": { version: "v2", hash: "0xDEF..." }  // Outlier
//     },
//     resolvedFrom: "MongoDBOASIS",  // Majority wins
//     conflictDetected: true
//   }
// }

3. Custom Provider Lists

For specific operations, choose exactly which providers to use:

// Save ONLY to blockchains (skip databases)
const result = await fetch(
  'https://api.oasisweb4.one/api/data/save-holon-to-providers',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...holonData,
      providers: [
        'EthereumOASIS',
        'SolanaOASIS',
        'PolygonOASIS',
        'IPFSOASIS'
      ]
    })
  }
);

Security Best Practices

1. Never Expose Private Keys

OASIS manages private keys for you. Never include them in your application:

// ❌ BAD - Don't do this
const wallet = createWallet('YOUR_PRIVATE_KEY_HERE');

// ✅ GOOD - Let OASIS manage keys
const wallet = await oasis.generateWallet(avatarId, 'SolanaOASIS');
// Private key stored encrypted in OASIS, never exposed

2. Use JWT Tokens Properly

// Store JWT securely (httpOnly cookie or secure storage)
// Refresh before expiry (24 hour lifetime)

async function refreshToken(oldToken: string) {
  const response = await fetch(
    'https://api.oasisweb4.one/api/avatar/refresh-token',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${oldToken}`
      }
    }
  );
  
  const result = await response.json();
  return result.result.newToken;
}

3. Validate All Inputs

OASIS validates, but you should too:

function validateAvatarData(data) {
  if (!data.username || data.username.length < 3) {
    throw new Error('Username must be at least 3 characters');
  }
  if (!data.email || !data.email.includes('@')) {
    throw new Error('Valid email required');
  }
  if (!data.password || data.password.length < 6) {
    throw new Error('Password must be at least 6 characters');
  }
}

Production Deployment

Hosted OASIS API

Production URL: https://api.oasisweb4.one

Features:

✅ 99.9% uptime SLA
✅ Auto-failover across 50+ providers
✅ Automatic scaling
✅ Global CDN
✅ DDoS protection
✅ Rate limiting (10,000 requests/hour free tier)

Pricing:

Free Tier: 10,000 requests/hour
Pro: $99/month - 100,000 requests/hour
Enterprise: Custom - Unlimited requests + SLA

Self-Hosted OASIS

For maximum control, run your own OASIS instance:

1. Clone Repository:

git clone https://github.com/NextGenSoftwareUK/OASIS.git
cd OASIS

2. Configure OASIS_DNA.json:

{
  "StorageProviders": {
    "AutoFailOverEnabled": true,
    "AutoReplicationEnabled": true,
    "AutoFailOverProviders": "MongoDBOASIS, ArbitrumOASIS, EthereumOASIS",
    "AutoReplicationProviders": "MongoDBOASIS, IPFSOASIS",
    
    "MongoDBOASIS": {
      "ConnectionString": "mongodb://your-mongo-url",
      "DBName": "OASIS_PROD"
    },
    "EthereumOASIS": {
      "ChainPrivateKey": "YOUR_PRIVATE_KEY",
      "ConnectionString": "https://mainnet.infura.io/v3/YOUR_KEY"
    },
    "SolanaOASIS": {
      "PrivateKey": "YOUR_SOLANA_KEY",
      "ConnectionString": "https://api.mainnet-beta.solana.com"
    }
  }
}

3. Run with Docker:

docker build -t oasis-api .
docker run -p 5002:5002 \
  -v $(pwd)/OASIS_DNA.json:/app/OASIS_DNA.json \
  -e ASPNETCORE_ENVIRONMENT=Production \
  oasis-api

4. Or run directly:

cd ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI
dotnet run

Common Integration Patterns

Pattern 1: User Data Sync

Use Case: Sync user profiles across multiple platforms

class UserService {
  constructor(private oasis: OASISClient) {}
  
  async createUser(username: string, email: string) {
    // Save to OASIS - automatically replicated to all providers
    const result = await this.oasis.saveData({
      type: 'UserProfile',
      username,
      email,
      createdAt: new Date(),
      platforms: {
        ethereum: true,
        solana: true,
        polygon: true
      }
    });
    
    // User can now login from ANY blockchain
    return result.result.id;
  }
  
  async getUserProfile(userId: string) {
    // Load from OASIS - automatic failover if provider down
    return await this.oasis.loadData(userId);
  }
}

Pattern 2: Cross-Chain Asset Tracking

Use Case: Track assets across multiple blockchains

class AssetTracker {
  async trackAsset(asset: any) {
    // Save asset data to all providers
    const result = await oasis.saveData({
      type: 'Asset',
      assetId: asset.id,
      chains: {
        ethereum: { address: '0xABC...', balance: 1000 },
        solana: { address: 'GHI...', balance: 500 },
        polygon: { address: '0xDEF...', balance: 750 }
      },
      totalValue: 2250,
      lastUpdated: new Date()
    });
    
    return result;
  }
  
  async getAssetAcrossChains(assetId: string) {
    // Returns unified view from all chains
    const asset = await oasis.loadData(assetId);
    
    // Even if Ethereum is down, you get data from Solana/Polygon
    return {
      totalValue: asset.totalValue,
      chains: asset.chains,
      source: asset.loadedFrom  // Shows which provider responded
    };
  }
}

Pattern 3: Decentralized Marketplace

Use Case: Build a marketplace where buyers and sellers use different chains

class Marketplace {
  async listItem(sellerId: string, item: any, acceptedChains: string[]) {
    // Save listing to all providers
    return await oasis.saveData({
      type: 'MarketplaceListing',
      itemId: item.id,
      sellerId,
      sellerChain: 'EthereumOASIS',
      price: item.price,
      acceptedChains,  // ['SolanaOASIS', 'PolygonOASIS', 'ArbitrumOASIS']
      status: 'active',
      listedAt: new Date()
    });
  }
  
  async getAllListings() {
    // Query returns ALL listings regardless of which chain they're on
    const listings = await oasis.searchData({
      type: 'MarketplaceListing',
      status: 'active'
    });
    
    // Buyers on ANY chain can see ALL listings
    return listings;
  }
  
  async purchase(listingId: string, buyerId: string, buyerChain: string) {
    // Load listing
    const listing = await oasis.loadData(listingId);
    
    // Process payment on buyer's chain
    // Transfer item on seller's chain
    // Update listing status across all providers
    
    await oasis.saveData({
      ...listing,
      status: 'sold',
      buyerId,
      buyerChain,
      soldAt: new Date()
    });
    
    // Both parties happy, cross-chain transaction complete
  }
}

API Reference Summary

Core Endpoints You'll Use Most

Endpoint

Method

Purpose

/api/avatar/register

POST

Create user account

/api/avatar/authenticate

POST

/api/data/save-holon

POST

Save data to all providers

/api/data/load-holon/{id}

GET

Load data with failover

/api/wallet/avatar/{id}/generate

POST

Generate blockchain wallet

/api/wallet/transfer

POST

Send tokens cross-chain

/api/nft/mint

POST

Mint cross-chain NFT

/api/provider/health

GET

Check provider status

Complete API Documentation

For full endpoint reference with all 500+ endpoints:

WEB4 OASIS API: /Volumes/Storage/OASIS_CLEAN/Docs/Devs/API Documentation/WEB4_OASIS_API_Documentation_Comprehensive.md
API Endpoints Summary: /Volumes/Storage/OASIS_CLEAN/OASIS_API_COMPLETE_ENDPOINTS_SUMMARY.md

Benefits for Your Application

1. Instant Multi-Chain Support

Without OASIS:

// You need separate integrations for each chain
const ethProvider = new EthereumProvider(...);
const solProvider = new SolanaProvider(...);
const polyProvider = new PolygonProvider(...);
// ... 47 more providers

// Save to each one separately
await ethProvider.save(data);
await solProvider.save(data);
await polyProvider.save(data);
// ... (nightmare)

With OASIS:

// One integration, works with all chains
const oasis = new OASISClient(token);
await oasis.saveData(data);
// Automatically saved to all 50+ providers

2. Built-in Failover

Your application never goes down because if MongoDB fails, OASIS uses Arbitrum. If Arbitrum fails, uses Ethereum. If Ethereum fails, uses Polygon. Etc.

Uptime: 99.999%+ (virtually impossible to have ALL 50+ providers fail simultaneously)

3. Unified User Identity

One avatar ID works across all blockchains. Users don't need separate accounts for each chain.

4. Automatic Backups

Data is automatically backed up to:

Fast database (MongoDB) for quick access
Permanent storage (IPFS) for immutability
Multiple blockchains (Ethereum, Arbitrum, etc.) for proof

You get enterprise-grade data redundancy for free.

Support & Resources

Documentation

This Guide: OASIS Provider Architecture
Full API Reference: OASIS_API_COMPLETE_ENDPOINTS_SUMMARY.md
HyperDrive Architecture: HYPERDRIVE_ARCHITECTURE_DIAGRAM.md

Example Code

JavaScript: /meta-bricks-main/src/app/services/oasis.service.ts
Node.js Backend: /meta-bricks-main/backend/storage/oasis-storage-utils.js
C# Integration: Contact @maxgershfield on Telegram for .NET SDK

Getting Help

Telegram: @maxgershfield
GitHub: https://github.com/NextGenSoftwareUK/OASIS

API Status

Production API: https://api.oasisweb4.one
Devnet API: http://devnet.oasisweb4.one
Swagger Docs: https://api.oasisweb4.one/swagger

Quick Start Checklist

Get OASIS API access (sign up or self-host)
Create an avatar account
Authenticate and get JWT token
Save your first holon (test with simple data)
Load data back (verify failover works)
Generate wallets for your users
Integrate with your application
Test on testnets before production
Deploy to production

Conclusion

The OASIS Provider Architecture gives you instant multi-chain, multi-database, multi-storage capabilities through a single API. Instead of integrating with 50+ providers separately (months of work), you integrate with OASIS once (hours of work) and get access to everything.

Key Value Propositions:

Speed to Market: Launch multi-chain in days instead of months
Cost Savings: One integration instead of 50+ separate integrations
Reliability: 100% uptime via automatic failover
Scalability: OASIS handles provider selection and load balancing
Future-Proof: New providers added to OASIS = your app supports them automatically

Your friend can start building interoperable systems TODAY with just a few API calls.

Document Version: 2.0 Last Updated: November 6, 2025 Contact: Telegram @maxgershfield License: Open for integration - Contact for partnership opportunities

PreviousQuick Start - Try in 30 Seconds NextAPI Reference - Essential Endpoints

Last updated 12 days ago

Good evening

Table of Contents

What is the OASIS Provider Architecture?

Overview

Key Concept: "Write Once, Store Everywhere"

How It Works

The Core Mechanism: HyperDrive

1. Auto-Replication

2. Auto-Failover

3. Auto-Load Balancing

Available Providers

✅ Currently Active & Configured

🔧 Built But Needs Configuration

Blockchain Providers (30+)

Database Providers (10+)

Storage Providers (5+)

Network Providers (5+)

Social Providers (5+)

Getting Started

Step 1: Get API Access

Step 2: Create an Avatar (User Account)

Step 3: Authenticate

API Endpoints

Core Pattern: Provider-Agnostic Operations

Save Data (with Auto-Replication)

Load Data (with Auto-Failover)

Specify Specific Provider (Optional)

Code Examples

JavaScript/TypeScript Example

Python Example

C# Example

Advanced Features

Multi-Chain Wallets

Cross-Chain NFTs

Provider Health Monitoring

Use Cases for Your Application

Use Case 1: Multi-Chain Game

Use Case 2: Social DApp

Use Case 3: Cross-Chain Marketplace

Advanced Features

1. Provider Selection Strategy

2. Conflict Resolution

3. Custom Provider Lists

Security Best Practices

1. Never Expose Private Keys

2. Use JWT Tokens Properly

3. Validate All Inputs

Production Deployment

Hosted OASIS API

Self-Hosted OASIS

Common Integration Patterns

Pattern 1: User Data Sync

Pattern 2: Cross-Chain Asset Tracking

Pattern 3: Decentralized Marketplace

API Reference Summary

Core Endpoints You'll Use Most

Complete API Documentation

Benefits for Your Application

1. Instant Multi-Chain Support

2. Built-in Failover

3. Unified User Identity

4. Automatic Backups

Support & Resources

Documentation

Example Code

Getting Help

API Status

Quick Start Checklist

Conclusion