# Amanah API and Developer Sandbox

Source human pages:

- https://amanah.finance/api
- https://developers.amanah.finance

OpenAPI contract:

- https://amanah.finance/openapi/amanah-b2b-api.yaml

This machine-readable page is derived from Amanah's existing public API and developer pages.

## Product Positioning

Amanah describes its API product as Halal Compliance as a Service: Shariah compliance intelligence for platforms, portfolios, and AI agents.

The API page says Amanah can add screening, Human Rights Risk intelligence, and grounded advisor chat to broker apps, robo-advisors, ETF/fund workflows, wealth platforms, and compliance teams.

The B2B API platform is packaged around outcomes. Amanah configures capabilities privately per client.

## Phase 1 API Surface

The public API page lists this Phase 1 surface:

- `GET /v1/screen/stock/{ticker}`
- `POST /v1/screen/stocks`
- `GET /v1/screen/stocks/catalog`
- `GET /v1/screen/stocks/catalog/export`
- `GET /v1/screen/hr-risk/{ticker}`
- `POST /v1/mcp`
- `GET /v1/ai/mcp/tools`

The page states that Phase 1 is listed stocks first and ETFs/funds are designed as coming soon.

## Product Families

The API page describes:

- B2B APIs for single-stock checks, bulk screening, market catalogues, exports, and separate Human Rights Risk Score results.
- MCP and advisor chat as a grounded tool layer for Amanah AI, frontier model apps, and later white-label assistant experiences.
- Developer sandbox with scoped evaluation keys, constrained markets, sample tickers, docs, and examples.

## Authentication and Access

The API page states:

- Use bearer API keys for every request.
- Create an Amanah account to generate a sandbox key in the developer portal.
- Production keys are issued after Amanah onboarding and entitlement setup.

Example shown on the public API page:

```http
Authorization: Bearer am_sandbox_...
```

Sandbox base URL:

```text
https://sandbox-api.amanah.finance
```

Production base URL:

```text
https://api.amanah.finance
```

## Sandbox

The developer page says the sandbox lets developers test Amanah stock screening and Human Rights Risk Score APIs with sample data, clear response contracts, and a sandbox key before custom production onboarding.

The developer page says:

- Sandbox keys are tied to Amanah accounts.
- Sandbox keys use curated sample data.
- Production keys are never issued automatically.
- Production access requires discovery, onboarding, and agreement.
- Sandbox and production are kept aligned through the OpenAPI contract and regression tests.

## Example Requests

Single stock:

```bash
curl \
  -H "Authorization: Bearer $AMANAH_API_KEY" \
  -H "X-Amanah-Environment: sandbox" \
  "https://api.amanah.finance/v1/screen/stock/AAPL"
```

Bulk screening:

```bash
curl -X POST \
  -H "Authorization: Bearer $AMANAH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tickers":["AAPL","MSFT"]}' \
  "https://api.amanah.finance/v1/screen/stocks"
```

Human Rights Risk Score:

```bash
curl \
  -H "Authorization: Bearer $AMANAH_API_KEY" \
  "https://api.amanah.finance/v1/screen/hr-risk/AAPL"
```

MCP endpoint:

```text
POST https://api.amanah.finance/v1/mcp
```

Tools listed on the public API page:

- `screen_stock`
- `bulk_screen_stocks`
- `get_hr_risk_score`
- `render_compliance_answer`

## Production Onboarding

The API page describes three steps:

1. Discovery: confirm use case, markets, response depth, Human Rights Risk Score needs, and AI/MCP requirements.
2. Configuration: configure allowed endpoints, response fields, methods, markets, quotas, and production key access privately for the tenant.
3. Go live: validate sandbox behavior, then Amanah issues production keys after onboarding, agreement, and entitlement approval.

## Important Guardrails

Do not invent endpoints, fields, response values, verdicts, ratios, Human Rights Risk Score values, or evidence links. Use the OpenAPI contract for endpoint names, schemas, response fields, errors, and examples.

Do not present API responses as investment advice or a Shariah ruling.