# Numeral (slim)

> Numeral is a hosted sales tax and VAT compliance service from Numeral Two, Inc. Its REST API calculates tax, records transactions and refunds, and manages exempt customers, and Numeral registers and files. A remote MCP server reads the account.

- Full: https://www.anchorterminal.com/tools/numeral.md (~7,700 tokens) · this version ~1,880 tokens · JSON https://www.anchorterminal.com/tools/numeral.json · canonical https://www.anchorterminal.com/tools/numeral
- Index: https://www.anchorterminal.com/llms.txt · API: https://www.anchorterminal.com/api/v1/index.json · Updated: 2026-10-09

**D · 49.3/100 · rank #611 of 722 · #10 in Tax calculation & compliance · not agent-ready · confidence medium**


Assessment: Docs are written for agents, with a public OpenAPI spec for 32 operations, Markdown pages, llms.txt and a remote MCP server whose 14 tools are read-only by default. No status page, numeric rate limit or SLA was found, the API ignores idempotency keys, and API access is sold on a custom plan after a demo.

## Facts

- Kind: HTTP API · vendor: Numeral Two, Inc. · category: Tax calculation & compliance · legal entity: Numeral Two, Inc. · provenance 53/100
- Endpoint: `https://api.numeralhq.com` (HTTP, Streamable HTTP)
- Auth: API key · pricing: Paid · x402: no · licence: Proprietary service under Numeral's terms of service. The Go, Python and Node SDKs are Apache-2.0
- Probe metrics: not measured yet (probes haven't run)
- API: 32 operations under https://api.numeralhq.com/tax in version 2026-03-01. OpenAPI 3.0.1 at https://docs.numeral.com/api-reference/v2026-03-01/openapi.json. Amounts are integers in minor units
- Versions: 2024-09-01, 2025-05-12, 2026-01-01 and 2026-03-01, chosen with the `X-API-Version` header. Merchant, platform and certificate endpoints need 2026-01-01 or later
- Calculation: `POST /tax/calculations` returns tax per line item and jurisdiction with an `expires_at`. `POST /tax/transactions` commits a `calculation_id` under a `reference_order_id` for filing. The best practices guide gives 24 hours as the calculation lifetime
- MCP server: Remote, stateless Streamable HTTP at https://mcp.numeralhq.com/mcp, POST only. 14 documented read-only tools. Four write tools gated per account. Health check at `GET /ping`
- Credentials: Secret API key as a Bearer token for both surfaces, `sk_test_` or `sk_prod_`. No scopes or OAuth. Revocation takes effect immediately per the MCP docs
- Rate limits: Not published. 429 on the API and 429 with JSON-RPC code -32005 on MCP, metered separately and per account. The docs advise exponential backoff
- Errors: From 2026-01-01, flat JSON with `code`, `type` and `message`, such as `ZIP_STATE_MISMATCH`. MCP tool errors return `error_code` and `error_message` with `isError` set
- Paging: Cursor paging with `has_more`. `limit` defaults to 10 with a maximum of 100 on merchants and certificates, and to 25 with a maximum of 100 on MCP list tools
- Sandbox: Test keys keep merchant, transaction and product data apart from production, and nothing is filed. Certificate endpoints are live only
- Pricing: Monitoring free. Professional $75 per filing and $150 per registration. Enterprise, which lists the tax engine and API, is custom
- SDKs: Go `github.com/NumeralHQ/numeral-tax-go` v0.1.0 (27 August 2026), Python `numeral-tax` 0.1.0a1 (18 December 2025), Node `numeral-tax` 0.1.0-alpha.2 (18 August 2026), generated by Stainless, Apache-2.0
- Agent docs: llms.txt, Markdown pages, and Claude skills installed with `npx skills add https://docs.numeralhq.com`, which reference an optional `numeral-api-docs` MCP server for the documentation
- Coverage: Numeral says all US jurisdictions and 90+ countries (https://www.numeral.com/product/api)
- Status: No status page found
- Prices: Filed return, Professional $75 per transaction; State registration, Professional $150 per transaction

- Scores: Reliability 25, Performance pending, Schema & documentation 87, Agent ergonomics 71, Security & auth 47, Payments & pricing 10, Task success pending, Maintenance & community 60, Transparency & trust 45 · total over the 7 assessed categories
- Why: Reliability, Graded on the REST API with the hosted lines, with the MCP server noted where it differs. · Schema & documentation, OpenAPI 3.0.1 at `docs.numeral.com/api-reference/v2026-03-01/openapi.json` with 32 operations and 74 schemas. · Agent ergonomics, List endpoints take `cursor`, and merchants and certificates take `limit` up to 100. No field selection. · Security & auth, Secret API keys as Bearer tokens, `sk_test_` or `sk_prod_`, created and revoked in the dashboard, with revocation immediate per the MCP docs… · Payments & pricing, No x402, MPP or L402 (0). · Maintenance & community, Closed service. · Transparency & trust, Closed service under terms last updated 10 June 2025 that name Numeral Two, Inc.
- Sources: 34, open questions: 9, both in the full twin
- Capabilities: tax.calculate, tax.transactions, tax.exemptions, tax.filing
- JSON: https://www.anchorterminal.com/api/v1/tools/numeral.json
- Verify (for the vendor): the badge `https://www.anchorterminal.com/badges/numeral.svg` or a link to https://www.anchorterminal.com/tools/numeral from a page on numeral.com or one of its subdomains, or the README of github.com/NumeralHQ/numeral-tax-go, then `POST https://www.anchorterminal.com/api/v1/verify` `{"slug", "url"}` or `verify_listing` at /mcp; re-checked weekly, no effect on the grade. Snippets in the full twin.

## Before you call it

1. Send `X-API-Version: 2026-03-01` on every call to `https://api.numeralhq.com`. Merchant, platform and certificate endpoints reject requests without it
2. Commit with a stable `reference_order_id`. On `REFERENCE_ORDER_ID_ALREADY_EXISTS` look up the existing transaction, because `Idempotency-Key` is ignored
3. Commit before the calculation's `expires_at`. If it has expired, calculate again and commit the new `calculation_id` with the original `reference_order_id`
4. Send `amount` as the line total in minor units to `/tax/calculations` and as the per-unit price to `/tax/platform/calculations`
5. Start with an `sk_test_` key. Certificate endpoints and MCP certificate tools are live only and answer `TESTMODE_NOT_SUPPORTED` or `live_mode_required`

## Connect

```bash
go get -u 'github.com/NumeralHQ/numeral-tax-go@v0.1.0'
```

```bash
curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 2026-03-01' \
  --data '{ ... }'
```

```bash
claude mcp add --transport http numeral https://mcp.numeralhq.com/mcp \
  --header "Authorization: Bearer sk_test_..."
```
Full config and headless snippets are in the full page. Through letme (picks today, calling later): https://letme.dev/numeral

## Similar tools

| Tool | Grade | Score | Shared capabilities | Slim |
| --- | --- | --- | --- | --- |
| Avalara AvaTax | B | 68.8 | tax.calculate, tax.transactions, tax.exemptions, tax.filing | https://www.anchorterminal.com/tools/avalara.min.md |
| Anrok | C | 61.6 | tax.calculate, tax.transactions, tax.exemptions, tax.filing | https://www.anchorterminal.com/tools/anrok.min.md |
| Kintsugi | C | 60.7 | tax.calculate, tax.transactions, tax.filing, tax.exemptions | https://www.anchorterminal.com/tools/kintsugi.min.md |
| Zamp | D | 49.5 | tax.calculate, tax.transactions, tax.filing, tax.exemptions | https://www.anchorterminal.com/tools/zamp.min.md |
| TaxJar | C | 57.6 | tax.calculate, tax.transactions, tax.exemptions | https://www.anchorterminal.com/tools/taxjar.min.md |


## Panel reviews (0, desk reviews from public material, no calls made)