Provider client for Super Protocol
npm install @super-protocol/provider-clientType-safe client for SuperProtocol Provider API, built on top of openapi-fetch.
- ✅ Type Safety - Automatic type generation from OpenAPI schema
- ✅ Modern API - Uses native fetch API
- ✅ Minimal Size - Only 6kb + openapi-fetch
- ✅ Auto Updates - Types generated on every build
- ✅ Auth Middleware - Automatic token injection in headers
``bash`
npm install @super-protocol/provider-client
`typescript
import { createProviderClient } from '@super-protocol/provider-client';
const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: process.env.SP_ACCESS_TOKEN // Get token through authentication
});
// Get current user information
const { data, error } = await client.GET('/api/auth/me');
if (data) {
console.log('User ID:', data.id);
}
`
1. Authenticate with SuperProtocol:
- Visit SuperProtocol Console
- Connect your wallet (MetaMask, WalletConnect, etc.)
- Your access token will be generated automatically
2. Alternative: Use the OAuth API:
- Use the /api/auth/token endpoint to get a token programmatically
- See the OAuth documentation for details
3. Set Environment Variable:
`bash
# Option 1: Export in your shell
export SP_ACCESS_TOKEN="your-jwt-token-here"
# Option 2: Create .env file (recommended)
echo "SP_ACCESS_TOKEN=your-jwt-token-here" > .env
# Option 3: Copy from example and edit
cp example.env .env
# Then edit .env with your actual token
`
4. Run the Example:
`bash
# The .env file will be loaded automatically (Node.js 20+)
npm run start:example
# Or run directly with token
SP_ACCESS_TOKEN="your-token" npm run start:example
`
Starting with Node.js 20+, environment variables from .env files are automatically loaded using the --env-file flag. This package is configured to use this feature.
Create a .env file in your project root:
`envSuperProtocol API Configuration
Get your token from https://console.superprotocol.com after connecting wallet
SP_ACCESS_TOKEN=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...your-full-token-here
Quick setup options:
`bash
Option 1: Create directly
echo "SP_ACCESS_TOKEN=your-token-here" > .envOption 2: Copy from example
cp .env.template .env
Then edit .env file with your actual token
`The
start:example script uses --env-file-if-exists=.env flag, which means:
- ✅ If .env file exists, variables are loaded automatically
- ✅ If .env file doesn't exist, no error is thrown
- ✅ Environment variables take precedence over .env file valuesFor more details, see the Node.js documentation on environment variables.
$3
This package includes a working example that demonstrates all major API endpoints:
`bash
Clone the repository
git clone https://github.com/super-protocol/sp-providers
cd sp-providers/packages/provider-clientInstall dependencies
npm installSet your access token (choose one method):
Method 1: Create .env file (recommended)
echo "SP_ACCESS_TOKEN=your-token-here" > .envMethod 2: Export environment variable
export SP_ACCESS_TOKEN="your-token-here"Method 3: Copy from example
cp example.env .env
Then edit .env with your actual token
Run the example (automatically loads .env if present)
npm run start:example
`The example will show you:
- ✅ Current user information
- ✅ User settings and storage configuration
- ✅ Wallet balance and address
- ✅ Available workflows
- ✅ Provider information
- ✅ Example POST request (workflow replenishment)
API Reference
$3
Creates a configured openapi-fetch client with auth middleware.
Parameters:
-
baseUrl? - API base URL (default: https://cp.dev.superprotocol.com)
- accessToken? - Authorization token (automatically added to headers)
- headers? - Additional HTTP headersReturns: Configured openapi-fetch client with typed
GET, POST, PUT, DELETE, etc. methods.Environment Variables:
-
SP_ACCESS_TOKEN - Access token for authentication (loaded from .env file automatically with Node.js 20+)
- SP_BASE_URL - Optional base URL override (defaults to https://cp.dev.superprotocol.com)Example environment configurations:
`bash
Development environment (default)
SP_BASE_URL=https://cp.dev.superprotocol.comStaging environment
SP_BASE_URL=https://cp.staging.superprotocol.comProduction environment
SP_BASE_URL=https://cp.superprotocol.com
`Usage Examples
$3
`typescript
import { createProviderClient } from '@super-protocol/provider-client';// With Node.js 20+ and --env-file flag, .env variables are automatically loaded
const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: process.env.SP_ACCESS_TOKEN // Loaded from .env file automatically
});
// GET request
const { data: userData, error } = await client.GET('/api/auth/me');
// POST request
const { data: workflow, error: workflowError } = await client.POST('/api/workflows', {
body: {
parentOrderInfo: { / ... / },
parentOrderSlot: { / ... / },
// All fields are typed automatically!
}
});
// PUT request with path parameters
const { data, error } = await client.PUT('/api/offers/{id}', {
params: {
path: { id: 'offer-id' }
},
body: {
name: 'Updated Offer Name'
}
});
`$3
`typescript
// Query parameters
const { data: offers } = await client.GET('/api/offers', {
params: {
query: {
limit: 10,
offset: 0
}
}
});// Path parameters
const { data: offer } = await client.GET('/api/offers/{id}', {
params: {
path: { id: 'specific-offer-id' }
}
});
// Combined path and query parameters
const { data: workflows } = await client.GET('/api/workflows/{id}', {
params: {
path: { id: 'workflow-id' },
query: { includeDetails: true }
}
});
`$3
`typescript
const { data, error, response } = await client.GET('/api/auth/me');if (error) {
// Typed errors based on endpoint
console.error('Status:', response.status);
console.error('Error:', error);
return;
}
// data is guaranteed to exist if no error
console.log('User:', data.id);
`$3
`typescript
// Create client with custom headers
const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: 'your-token',
headers: {
'X-Custom-Header': 'value',
'User-Agent': 'MyApp/1.0'
}
});// Add additional middleware
client.use({
onRequest({ request }) {
console.log(
Making request to ${request.url});
return request;
},
onResponse({ response }) {
console.log(Response status: ${response.status});
return response;
}
});
`Supported Endpoints
The client supports all SuperProtocol API endpoints with full typing:
$3
- GET /api/auth/me - Current user information
- POST /api/auth/token - Get tokens
- POST /api/auth/refresh-access - Refresh token
- GET /api/auth/logout - Logout$3
- GET /api/users/nonce/{address} - Get nonce
- POST /api/users - Register user$3
- GET /api/users/me/wallet - Wallet information
- POST /api/users/me/wallet/withdraw - Withdraw funds$3
- GET /api/workflows - List workflows
- GET /api/workflows/{id} - Get specific workflow
- POST /api/workflows - Create workflow
- PATCH /api/workflows/{id} - Update workflow
- POST /api/workflows/{orderId}/replenish - Replenish workflow
- POST /api/workflows/{orderId}/cancel - Cancel workflow$3
- GET /api/providers - Provider information
- POST /api/providers - Create provider
- PATCH /api/providers/{id} - Update provider$3
- POST /api/offers - Create offer
- GET /api/offers/{id} - Get offer
- PATCH /api/offers/{id} - Update offer
- POST /api/offers/{offerId}/publish - Publish offer
- POST /api/offers/{id}/slots - Add slot$3
- POST /api/files - Upload file
- POST /api/files/list - List files
- GET /api/files/{id} - Get file
- POST /api/contents - Create content
- GET /api/contents/{id} - Get content$3
- GET /api/storages - List storages
- GET /api/storages/{id} - Get specific storage
- GET /api/user-settings - User settings
- PATCH /api/user-settings - Update settings$3
- POST /api/faucet/request-tokens - Request faucet tokens
- GET /health/liveness - Health check
- GET /health/readiness - Readiness checkType Generation
Types are automatically generated from OpenAPI schema during build:
`bash
npm run generate-types # Manual type generation
npm run build # Includes type generation
``Thanks to openapi-typescript integration, the client provides:
- ✅ Autocomplete for all available endpoints
- ✅ Type validation for request/response
- ✅ Parameter checking at compile time
- ✅ IntelliSense in VS Code and other IDEs
- ✅ Typed errors for each endpoint
| Library | Size (min) | Performance |
| -------------------------- | ---------- | -------------------- |
| @super-protocol/provider-client | 6 kB | 300k ops/s (fastest) |
| axios | 32 kB | 225k ops/s (slower) |
| superagent | 55 kB | 50k ops/s (6× slower) |
BSL-1.1
---
Built with ❤️ by SuperProtocol team