API Overview & Authentication

This section covers base URLs, authentication, rate limiting, error handling, and security best practices.

Base URL

All API requests should be made to the following base URL: Test Environment:

https://beta.stablesrail.io/v1/

Production Environment:

https://api.strails.io/v1/

Authentication Methods

API Key Authentication

All API requests require a valid API key included in the request headers.

HTTP Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Obtaining API Keys

If you haven’t received your API key yet, please contact our team to complete your onboarding process. You will receive an email with detailed steps on how to obtain your x-api-key.

Rate Limiting

Each API endpoint type has specific rate limits to ensure fair usage and system stability. Refer to the table below for the allowed request rates per endpoint category.

If your backend encounters rate limits often, consider implementing a queue to process requests asynchronously. This approach allows your system to handle actions in an eventually consistent manner, reducing the likelihood of hitting limits.If your use case requires higher rate limits, contact our team with details about your application and traffic patterns. We will review your request and discuss possible adjustments.

Rate Limits

Notes

Rates below were extracted from the functions code (withRateLimit options) and converted to a human-friendly “requests per minute (rpm)” where needed. For endpoints that do not set a per-endpoint limit the service default is used: window = 60,000 ms, maxPerWindow = 30 → 30 rpm.
Where the configured window is longer than 60s we show both the configured limit (max requests per window) and the equivalent rpm in the table.

User Management & Authentication

Endpoint	Configured limit	Equivalent (rpm)
`/onboarduser` (user registration)	100 requests / 60,000 ms	100 rpm
`/onboardstatus` (user status)	200 requests / 60,000 ms	200 rpm
`/getuserdetails`	100 requests / 60,000 ms	100 rpm
`/manageuserstatus`	default → 30 requests / 60,000 ms	30 rpm
`/listfintechusers`	100 requests / 60,000 ms	100 rpm

Virtual Accounts & Wallet Operations

Endpoint	Configured limit	Equivalent (rpm)	Notes
`/getvirtualaccount`	100 requests / 600,000 ms	10 rpm	configured as 100 requests per 10 minutes
`/getfintechvirtualaccount`	default → 30 requests / 60,000 ms	30 rpm	fintech onramp account retrieval

Wallet Management

Endpoint	Configured limit	Equivalent (rpm)
`/getfintechwallet`	default → 30 requests / 60,000 ms	30 rpm
`/addexternalwallet`	default → 30 requests / 60,000 ms	30 rpm
`/updateexternalwalletstatus`	default → 30 requests / 60,000 ms	30 rpm
`/removeexternalwallet`	default → 30 requests / 60,000 ms	30 rpm
`/listuserwallets`	100 requests / 60,000 ms	100 rpm
`/migrateuserwallets`	default → 30 requests / 60,000 ms	30 rpm

Transactions & Asset Management

Endpoint	Configured limit	Equivalent (rpm)	Notes
`/cngnonramp`	1000 requests / 600,000 ms	100 rpm	large batch/funding flows often use 10 minute windows
`/cngnofframp`	1000 requests / 600,000 ms	100 rpm
`/cngnonrampstatus`	default → 30 requests / 60,000 ms	30 rpm
`/cngnofframpstatus`	default → 30 requests / 60,000 ms	30 rpm
`/withdrawasset`	30 requests / 60,000 ms	30 rpm
`/fintechtransfer`	default → 30 requests / 60,000 ms	30 rpm
`/initiateofframp`	default → 30 requests / 60,000 ms	30 rpm
`/getofframpstatus`	default → 30 requests / 60,000 ms	30 rpm
`/deposits`	100 requests / 60,000 ms	100 rpm	list deposit transactions
`/payouts`	100 requests / 60,000 ms	100 rpm	list payout transactions
`/transactions`	100 requests / 60,000 ms	100 rpm	list all transactions

Fintech Fee Management

The following endpoints allow fintechs to manage and retrieve accumulated fees, request withdrawals of collected fees, and configure fee rates for onramp/offramp flows.

Endpoint	Configured limit	Equivalent (rpm)
`/getwithdrawalhistory` (fintech-withdrawalhistory)	100 requests / 60,000 ms	100 rpm
`/feewithdrawal` (fintech-requestwithdrawal)	30 requests / 60,000 ms	30 rpm
`/getaccumulatedfees` (accumulated-fintech-fees)	60 requests / 60,000 ms	60 rpm
`/managefees` (manage-fees)	30 requests / 60,000 ms	30 rpm
`/getfees` (get-fees)	60 requests / 60,000 ms	60 rpm
`/fees/strails/preview` (strails-fee-preview)	60 requests / 60,000 ms	60 rpm
`/verify-withdrawal` (verify-withdrawal)	30 requests / 60,000 ms	30 rpm

Bank Account Management

The following endpoints allow fintechs to manage Nigerian bank accounts for offramp (fiat payout) operations.

Endpoint	Configured limit	Equivalent (rpm)
`/getbankscode`	default → 30 requests / 60,000 ms	30 rpm
`/addbankaccount`	default → 30 requests / 60,000 ms	30 rpm
`/updatebankaccount`	default → 30 requests / 60,000 ms	30 rpm
`/deletebankaccount`	default → 30 requests / 60,000 ms	30 rpm
`/getbankaccounts`	default → 30 requests / 60,000 ms	30 rpm
`/listbankaccounts`	default → 30 requests / 60,000 ms	30 rpm

FX Orderbook & Trading Management

The following endpoints allow fintechs to create liquidity orders and execute FX trades.

Endpoint	Configured limit	Equivalent (rpm)	Notes
`/fx/orders`	30 requests / 60,000 ms	30 rpm	create orderbook order
`/fx/orders/:orderId`	30 requests / 60,000 ms	30 rpm	update orderbook order
`/fx/orders/:orderId`	30 requests / 60,000 ms	30 rpm	delete orderbook order
`/fx/orders/my-orders`	100 requests / 60,000 ms	100 rpm	list your orders
`/fx/orderbook`	100 requests / 60,000 ms	100 rpm	get public orderbook
`/fx/orderbook/stats`	60 requests / 60,000 ms	60 rpm	orderbook statistics
`/fx/orderbook-token`	30 requests / 60,000 ms	30 rpm	generate Firebase token
`/fx/quote`	60 requests / 60,000 ms	60 rpm	generate trade quote
`/fx/trade`	30 requests / 60,000 ms	30 rpm	execute trade
`/fx/market-order`	30 requests / 60,000 ms	30 rpm	execute market order
`/fx/trades/:tradeId`	60 requests / 60,000 ms	60 rpm	get trade status
`/v1/fx/trades`	100 requests / 60,000 ms	100 rpm	list your trades
`/swaptrigger`	30 requests / 60,000 ms	30 rpm	trigger async token swap
`/swap`	30 requests / 60,000 ms	30 rpm	swap on user’s smart wallet
`/swapstatus`	60 requests / 60,000 ms	60 rpm	get swap request status

Configuration & Management

Endpoint	Configured limit	Equivalent (rpm)
`/fx/mpc/register`	default → 30 requests / 60,000 ms	30 rpm
`/fx/settings`	default → 30 requests / 60,000 ms	30 rpm
`/fx/auto-signing/enable`	default → 30 requests / 60,000 ms	30 rpm
`/fx/auto-signing/disable`	default → 30 requests / 60,000 ms	30 rpm
`/fx/auto-signing/threshold`	default → 30 requests / 60,000 ms	30 rpm
`/fx/auto-signing/status`	default → 30 requests / 60,000 ms	30 rpm
`/fx/auto-signing/stats`	default → 30 requests / 60,000 ms	30 rpm
`/manageipallowlist`	default → 30 requests / 60,000 ms	30 rpm
`/regenerateapikey`	default → 30 requests / 60,000 ms	30 rpm
`/updateonrampasset`	default → 30 requests / 60,000 ms	30 rpm
`/autosigning/config`	default → 30 requests / 60,000 ms	30 rpm

Webhooks & Third-Party Integration

Endpoint	Configured limit	Equivalent (rpm)
`/setwebhook`	10 requests / 60,000 ms	10 rpm
`/togglewebhookstatus`	10 requests / 60,000 ms	10 rpm
`/getwebhook`	10 requests / 60,000 ms	10 rpm

Handling Rate Limits

When you exceed rate limits, the API returns a 429 Too Many Requests response:

{
  "status": "error",
  "response_code": "429",
  "message": "Too many requests. Please try again later.",
  "data": {
    "error": "Rate limit exceeded",
    "retry_after": 60
  }
}

Error Handling

Standard Error Response

{
  "status": "error",
  "response_code": "400",
  "message": "Human-readable error message",
  "data": {
    "error": "Validation failed",
    "details": {
      "field": "Additional error details"
    }
  }
}

Common Error Codes

The following error codes apply globally across all API endpoints:

Code	HTTP Status	Description
`AUTHENTICATION_FAILED`	401	Invalid or missing API key
`AUTHORIZATION_FAILED`	403	Insufficient permissions
`VALIDATION_ERROR`	400	Invalid request parameters
`NOT_FOUND`	404	Resource not found
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Complete Reference: For a comprehensive list of all status codes, error codes, and state transitions, see the API Status & Error Reference.API-Specific Errors: Each API also has domain-specific error codes documented in their respective sections:

Security Best Practices

API Key Management

Store Securely: Never commit API keys to version control
Use Environment Variables: Store keys in environment variables
Rotate Regularly: Rotate API keys periodically
Limit Scope: Use minimal required permissions for who or what service should have access to your keys.

Request Security

Use HTTPS: Always use secure connections
Validate Responses: Check response status and structure
Implement Timeouts: Set reasonable request timeouts
Log Carefully: Avoid logging sensitive data

Public Key / Encryption (store-public-key)

You may opt into an encryption feature where sensitive payloads are encrypted before being sent to Strails. To enable this, Use /storepublickey endpoint. This allows Strails to store the fintech’s public key material for encrypting responses or for verifying encrypted requests.

Endpoint

POST /storepublickey

Request body (example)

{
  "data": "<hex-encoded-ciphertext>",
}

​API Overview & Authentication

​Base URL

​Authentication Methods

​API Key Authentication

​Obtaining API Keys

​Rate Limiting

​Rate Limits

​Notes

​User Management & Authentication

​Virtual Accounts & Wallet Operations

​Wallet Management

​Transactions & Asset Management

​Fintech Fee Management

​Bank Account Management

​FX Orderbook & Trading Management

​Configuration & Management

​Webhooks & Third-Party Integration

​Handling Rate Limits

​Error Handling

​Standard Error Response

​Common Error Codes

​Security Best Practices

​API Key Management

​Request Security

​Public Key / Encryption (store-public-key)

​Endpoint

​Request body (example)

API Overview & Authentication

Base URL

Authentication Methods

API Key Authentication

Obtaining API Keys

Rate Limiting

Rate Limits

Notes

User Management & Authentication

Virtual Accounts & Wallet Operations

Wallet Management

Transactions & Asset Management

Fintech Fee Management

Bank Account Management

FX Orderbook & Trading Management

Configuration & Management

Webhooks & Third-Party Integration

Handling Rate Limits

Error Handling

Standard Error Response

Common Error Codes

Security Best Practices

API Key Management

Request Security

Public Key / Encryption (store-public-key)

Endpoint

Request body (example)