blackwalltier-com Receipts API
The Receipts API from blackwalltier-com — 2 operation(s) for receipts.
The Receipts API from blackwalltier-com — 2 operation(s) for receipts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/blackwalltier-com:blackwalltier-com-receipts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Black_Wall Receipts API
description: 'Pre-action outcome prediction for AI agents.
Your AI agent has a twin. The twin tries it first.
Black_Wall is a token-metered REST API. Send your agent''s proposed action;
we return a predicted outcome, a 0–100 risk score, a list of red flags,
a reversibility class + rollback cost, and a GO / CAUTION / STOP recommendation
in a few seconds — before the action runs.
Free tier: ~100 forecasts/mo, no credit card. Get a key at https://blackwalltier.com'
version: 1.0.0
contact:
name: Black_Wall Support
email: hello@forecast.dev
url: https://blackwalltier.com
servers:
- url: https://blackwalltier.com/api
description: Production
- url: http://localhost:3000/api
description: Local development
security:
- bearerAuth: []
tags:
- name: Receipts
paths:
/v1/receipts/{id}:
get:
summary: Look up a previously-issued decision receipt
description: 'Returns the envelope metadata (hashes + Ed25519 signature) for a
receipt issued by an earlier `/v1/forecast` call. Black_Wall stores
only the envelope — never the raw request or response bodies — so this
endpoint returns the cryptographic fingerprint, not the payloads.
Auth: requires the same Bearer key that issued the receipt.
Cross-tenant lookups return 404, not 403 (does not leak existence).
To verify, combine this envelope with your stored copy of the original
request + response and POST to `/v1/receipts/verify`.'
operationId: getReceipt
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The receipt ID returned in the `/v1/forecast` response under `receipt.id`.
responses:
'200':
description: Receipt envelope
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found, or owned by a different tenant
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Receipts
/v1/receipts/verify:
post:
summary: Verify a decision receipt (stateless, public)
description: 'Public, no API key required. Verifies an Ed25519 decision receipt
against the request + response bodies you provide. Intended for
auditors and any third party who needs to confirm that Black_Wall
actually signed off on a specific (request, response) pair.
Stateless: no database lookup. The receipt envelope carries the
`key_id`; we load the matching published public key from
`/.well-known/blackwall-signing-keys.json` and verify the signature
over the canonical hashes of your bodies.
If you want to verify entirely offline (no network call to Black_Wall):
cache the public key from the well-known URL and run the same
Ed25519 verify locally — this endpoint is a convenience, not a trust
dependency.
Strip the UNSIGNED top-level keys from your response_body before
posting — the signature is over the response without them:
* `receipt` — the envelope cannot sign itself.
* `confirmation` — the confirmation handle, added AFTER signing
on any held gate (CONFIRM / HUMAN_REQUIRED).
* `receipt_unavailable` — the reason no receipt was issued.
Every other field in the body IS signed. (We tolerate it if you forget
those three; we''ll strip them for you. Any OTHER unexpected key is left
in place and fails as `response_hash_mismatch` — response_hash is the
only thing binding the body, so unknown keys are never ignored.)'
operationId: verifyReceipt
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- envelope
- request_body
- response_body
properties:
envelope:
$ref: '#/components/schemas/Receipt'
request_body:
type: object
description: The exact body you originally POSTed to `/v1/forecast`.
additionalProperties: true
response_body:
type: object
description: The exact response body returned by `/v1/forecast`, with the unsigned top-level keys removed (`receipt`, `confirmation`, `receipt_unavailable`).
additionalProperties: true
responses:
'200':
description: Verification result
content:
application/json:
schema:
type: object
required:
- valid
- reason
properties:
valid:
type: boolean
reason:
type: string
description: 'A VERDICT about the receipt. One of:
ok | request_hash_mismatch | response_hash_mismatch |
signature_invalid | unknown_key_id |
unsupported_receipt_version | decision_hash_missing |
decision_hash_mismatch | decision_hash_unsigned
`unknown_key_id` means the envelope names a key_id we do
not publish, so we never issued that receipt. It is a
verdict, not an error: key_id is caller-supplied, and an
unrecognised one must not be able to produce a 5xx.
`verification_error` is returned with 400, not 200 — see
below. A verdict is never reached with HTTP 503.
'
example: ok
'400':
description: 'The request could not be processed: the body is not a JSON object,
a required field is missing, or the envelope could not be parsed
(`bad_request` / `missing_fields` / `verification_error`). Shape is
`{valid: false, reason, message}`.
'
content:
application/json:
schema:
type: object
required:
- valid
- reason
properties:
valid:
type: boolean
description: Always false on a 400.
reason:
type: string
enum:
- bad_request
- missing_fields
- verification_error
message:
type: string
description: Human-readable explanation of what was wrong.
'503':
description: 'NO VERDICT WAS REACHED. We publish a key for the `key_id` on the
envelope and could not load it — the value is unset or is not an
importable Ed25519 key — so this endpoint cannot say anything about
the receipt. `reason` is `verifier_unavailable`.
A `key_id` we do NOT publish is a different answer:
`200 unknown_key_id`. We never published that key, so we never
issued that receipt — that is a verdict, and it stays 200 because
`key_id` is caller-supplied and an unrecognised one must not be able
to produce a 5xx.
DO NOT treat this as a failed verification. The receipt may be
perfectly genuine; the fault is ours. Honour `Retry-After` and ask
again, or verify offline against a public key you already cached.
Before 2026-10-11 this condition was served as
`200 {valid: false, reason: "signature_invalid"}` — i.e. a genuine
receipt was reported as forged, with a success status. If you have
logic keyed on that, it was always wrong and this is the fix.
'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
Cache-Control:
schema:
type: string
enum:
- no-store
description: 'Always `no-store`. An outage must not be cached: a shared cache pinning this response would turn a momentary misconfiguration into minutes of refused verification.'
content:
application/json:
schema:
type: object
required:
- valid
- reason
properties:
valid:
type: boolean
description: 'Always false. Present because the schema requires it and
because false is the safe direction — never read it as a
statement that the receipt is invalid. The status code and
`reason` are what carry the meaning here.
'
reason:
type: string
enum:
- verifier_unavailable
tags:
- Receipts
components:
schemas:
Receipt:
type: object
description: 'Cryptographic decision receipt — an Ed25519 signature over canonical
hashes of the request + response of a single forecast call. Anyone
with the published public key (see /.well-known/blackwall-signing-keys.json)
can verify offline without contacting Black_Wall.
We sign and store HASHES ONLY — the raw request/response bodies are
never persisted on our side. To verify later, you (or your auditor)
provide the bodies and we re-hash to check against the signed envelope.
'
required:
- id
- forecast_id
- issued_at
- algorithm
- key_id
- request_hash
- response_hash
- signature
properties:
id:
type: string
description: Receipt's own UUID (distinct from forecast_id).
example: 1b3f25a8-9c4e-4f0a-9b1d-2d0e5c6b7a89
forecast_id:
type: string
description: The forecast this receipt vouches for.
issued_at:
type: string
format: date-time
algorithm:
type: string
enum:
- ed25519
key_id:
type: string
description: 'Which signing key was used. Look it up in
/.well-known/blackwall-signing-keys.json. Receipts issued before
a key rotation continue to verify against the retired key.
'
example: k1
request_hash:
type: string
description: SHA-256 (hex) of canonical(request_body), prefixed `sha256:`.
example: sha256:9af4...8c2e
response_hash:
type: string
description: SHA-256 (hex) of canonical(response_body without receipt), prefixed `sha256:`.
example: sha256:3d1c...e7b0
signature:
type: string
description: Base64url Ed25519 signature over the canonicalized envelope (minus signature).
verify_url:
type: string
format: uri
description: Convenience URL for POST verification.
example: https://blackwalltier.com/api/v1/receipts/verify
Error:
type: object
properties:
error:
type: string
description: Machine-readable error slug
example: insufficient_tokens
message:
type: string
description: Human-readable explanation
details:
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'Pass your API key as a Bearer token in the Authorization header.
Keys are prefixed `bw_live_` (or `bw_test_` if you''re in test mode).
'