Toyyib Developer Platform

Add Shariah stock screening to your product.

Query NGX equities, analyze user portfolios, monitor API usage, and access compliance reports through a server-side API-key integration.

Start buildingView endpoints

API base URL

Sandbox and production keys

Base URL
https://api.toyyib.app/api/v1

X-API-Key: sk_test_your_key_here

8

endpoints

API

keys

JSON

responses

Stocks

Search, filter, and sort NGX equities.

Portfolio scoring

Analyze holdings and purification amounts.

Reports

Retrieve compliance reports for equities.

Usage

Monitor daily quota and API key activity.

Getting started

Authenticate with X-API-Key

Every external API request requires an API key in the X-API-Key header. Sandbox keys use sk_test_ and production keys use sk_live_.

Key formats

sk_test_

Sandbox key for development and testing.

sk_live_

Production key for live data access.

Never expose API keys in browser code, public repositories, or client-side requests. Keep requests on your server.
cURL
curl "https://api.toyyib.app/api/v1/stocks" \
  -H "X-API-Key: sk_test_your_key_here"

Traffic controls

Rate limits are enforced per API key

Responses include rate-limit headers so your application can display remaining quota and back off gracefully.

X-RateLimit-Limit

Maximum requests in the current window

X-RateLimit-Remaining

Requests remaining in the window

X-RateLimit-Reset

UTC timestamp when the window resets

Retry-After

Seconds to wait after a 429 response

Error handling

Predictable JSON errors

The API uses standard HTTP status codes and wraps validation, authentication, authorization, and server errors in a consistent shape.

400VALIDATION_ERRORInvalid request parameters
401INVALID_API_KEYMissing or invalid API key
403FEATURE_UNAVAILABLEFeature unavailable for this key
404NOT_FOUNDResource does not exist
429RATE_LIMIT_EXCEEDEDToo many requests
500INTERNAL_ERRORUnexpected server error
Error format
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked.",
    "details": {}
  }
}
GET/api/v1/stocks

Stocks

List Stocks

Retrieve a paginated list of NGX stocks with optional filtering, searching, and sorting.

Parameters

status

string

Filter by compliant, non_compliant, doubtful, or pending.

sector

string

Filter by sector name, case-insensitive.

search

string

Search by ticker symbol or company name.

sort_by

string

Sort by symbol, price, change_percent, or market_cap.

page

integer

Page number. Defaults to 1.

curl
curl "https://api.toyyib.app/api/v1/stocks?status=compliant&sector=Industrial%20Goods&page=1" \
  -H "X-API-Key: sk_test_your_key_here"
Response
{
  "success": true,
  "data": {
    "stocks": [
      {
        "id": "019432a1-...",
        "ticker": "DANGCEM",
        "exchange": "NGX",
        "symbol": "NGX:DANGCEM",
        "name": "Dangote Cement Plc",
        "sector": "Industrial Goods",
        "price": "290.00",
        "change_percent": "1.58",
        "market_cap": "4940000000000",
        "status": "compliant"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_pages": 5,
      "total_items": 50,
      "has_next": true,
      "has_previous": false
    }
  },
  "message": "Stocks retrieved successfully"
}
GET/api/v1/stocks/{stock_identifier}

Stocks

Stock Details

Retrieve full details for one stock, including financials and Shariah screening ratios. Use a public ticker or exchange-qualified symbol, not the internal database ID.

Parameters

stock_identifier

string

Public ticker or exchange-qualified symbol, for example DANGCEM or NGX:DANGCEM.

curl
curl "https://api.toyyib.app/api/v1/stocks/NGX:DANGCEM" \
  -H "X-API-Key: sk_test_your_key_here"
Response
{
  "success": true,
  "data": {
    "id": "019432a1-...",
    "ticker": "DANGCEM",
    "exchange": "NGX",
    "symbol": "NGX:DANGCEM",
    "name": "Dangote Cement Plc",
    "sector": "Industrial Goods",
    "price": "290.00",
    "change_percent": "1.58",
    "market_cap": "4940000000000",
    "status": "compliant",
    "shariah_metrics": {
      "debt_ratio": 20.0,
      "interest_income": 1.2,
      "non_compliant_income": 0.8,
      "liquid_assets": 15.0,
      "compliance_score": 92
    }
  },
  "message": "Stock details retrieved successfully"
}
GET/api/v1/stocks/sectors

Stocks

Sector Summaries

Retrieve sector-level stock counts, compliant counts, and average compliance scores.

Parameters

This endpoint takes no parameters.

curl
curl "https://api.toyyib.app/api/v1/stocks/sectors" \
  -H "X-API-Key: sk_test_your_key_here"
Response
{
  "success": true,
  "data": {
    "sectors": [
      {
        "name": "Banking",
        "stock_count": 12,
        "compliant_count": 8,
        "average_compliance_score": 78.5
      }
    ]
  },
  "message": "Sectors retrieved successfully"
}
POST/api/v1/portfolio/analyze

Portfolio

Analyze Portfolio

Submit holdings and receive portfolio-level compliance scoring, value breakdowns, and purification amounts.

Parameters

holdings

array

One to fifty holdings, with no duplicate tickers.

holdings[].ticker

string

Ticker symbol, case-insensitive.

holdings[].shares

number

Number of shares held. Minimum 1.

curl
curl -X POST "https://api.toyyib.app/api/v1/portfolio/analyze" \
  -H "X-API-Key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"ticker": "DANGCEM", "shares": 500},
      {"ticker": "BUACEMENT", "shares": 200}
    ]
  }'
Response
{
  "success": true,
  "data": {
    "summary": {
      "total_value": 1250000.0,
      "compliance_score": 72,
      "compliance_status": "doubtful",
      "total_purification_amount": 1523.45,
      "holdings_count": 2,
      "analyzed_at": "2026-04-12T10:30:00Z"
    },
    "holdings": [
      {
        "ticker": "DANGCEM",
        "value": 125000.0,
        "weight": 10.0,
        "compliance_status": "compliant",
        "purification_amount": 0.0
      }
    ]
  },
  "message": "Portfolio analysis completed successfully"
}
GET/api/v1/reports

Reports

List Reports

Retrieve paginated compliance reports.

Parameters

type

string

Filter by monthly, quarterly, or special.

page

integer

Page number.

curl
curl "https://api.toyyib.app/api/v1/reports?type=quarterly&page=1" \
  -H "X-API-Key: sk_live_your_pro_key"
Response
{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "019432b2-...",
        "title": "Q1 2026 Compliance Report",
        "type": "quarterly",
        "created_at": "2026-01-15T00:00:00Z"
      }
    ]
  },
  "message": "Reports retrieved successfully"
}
GET/api/v1/reports/stats

Reports

Report Statistics

Get report generation and download statistics, including upcoming report schedules.

Parameters

This endpoint takes no parameters.

curl
curl "https://api.toyyib.app/api/v1/reports/stats" \
  -H "X-API-Key: sk_live_your_pro_key"
Response
{
  "success": true,
  "data": {
    "total_reports_generated": 24,
    "total_downloads": 156,
    "report_schedule": [
      {
        "type": "monthly",
        "description": "Generated on the 15th of each month",
        "next_report_date": "2026-03-15T00:00:00"
      }
    ]
  },
  "message": "Report statistics retrieved successfully"
}
GET/api/v1/reports/{report_id}/download

Reports

Download Report

Get a download URL for a specific compliance report.

Parameters

report_id

uuid

The report unique identifier.

curl
curl "https://api.toyyib.app/api/v1/reports/019432b2-.../download" \
  -H "X-API-Key: sk_live_your_enterprise_key"
Response
{
  "success": true,
  "data": {
    "download_url": "https://api.toyyib.app/media/reports/q1-2026.pdf",
    "file_name": "Q1 2026 Compliance Report.pdf",
    "file_size": 245760
  },
  "message": "Download URL generated successfully"
}
GET/api/v1/usage

Account

API Usage

Check current API key usage and rate-limit status.

Parameters

This endpoint takes no parameters.

curl
curl "https://api.toyyib.app/api/v1/usage" \
  -H "X-API-Key: sk_test_your_key_here"
Response
{
  "success": true,
  "data": {
    "key": {
      "prefix": "sk_test_abc12345",
      "name": "My Dev Key",
      "mode": "sandbox",
      "is_active": true
    },
    "usage": {
      "daily_limit": 1000,
      "daily_used": 142,
      "daily_remaining": 858,
      "per_minute_limit": 30
    }
  },
  "message": "Usage data retrieved successfully"
}

Ready to add Shariah compliance to your platform?

Talk to the Halcore team about API keys, sandbox access, and business onboarding.

Schedule a demoBack to Toyyib