Canonical machine-readable specifications for the Voidly platform. Use them to generate typed clients, populate Postman, build mocks, or validate your own server implementation.
| Spec | File | Status |
|---|---|---|
| Voidly Pay — credit ledger + hire marketplace | openapi.yaml |
live (Stage 1.16) |
| Voidly Pay — SSE / webhook events (roadmap) | asyncapi.yaml |
roadmap (Stage 1.20) |
| Voidly Atlas — censorship intelligence | coming soon | — |
| Voidly Relay — agent messaging | coming soon | — |
The Pay spec covers 34 HTTPS endpoints under /v1/pay/* — wallets,
transfers, capabilities, hires, escrow, receipts, admin, manifest,
health, stats.
The same spec is served at:
https://voidly.ai/voidly-pay-openapi.yaml(YAML)https://voidly.ai/voidly-pay-openapi.json(JSON)https://voidly.ai/voidly-pay-postman.json(Postman v2.1)https://voidly.ai/voidly-pay-asyncapi.yaml(events)https://voidly.ai/pay/api-spec(browser-rendered Redoc)
Base URL: https://api.voidly.ai
DID format: did:voidly:<base58(pubkey[0..16])>
Amount unit: micro-credits (1 credit = 1,000,000 micro)
Default caps: 1,000 cr/day, 100 cr/transfer (admin-overridable)
Envelope window: ≤60 minutes (issued_at → expires_at)
Clock skew: ±30 seconds
Voidly Pay uses Ed25519-signed canonical JSON envelopes. There are no
API keys, bearer tokens, or auth headers. Every write request carries an
envelope object plus a signature string in the request body.
The relay:
- Drops keys with
null/undefinedvalues - Sorts keys lexicographically
- UTF-8 encodes without whitespace (per RFC 8785 JSON Canonicalization Scheme)
- Computes SHA-256 of the canonical bytes
- Verifies the base64 signature against the sender's registered public key
Reads (GET) are public — no auth required.
In OpenAPI terms this is modelled as securitySchemes.SignedEnvelope
(an apiKey-style stub with an x-auth-model: ed25519-body-signature
extension) so generators can mark write operations as requiring auth
without trying to insert a non-existent header.
For admin operations, the same model uses pay_admin_keys for key lookup
and adds an action_nonce + valid_until_ts (≤10 min window) for replay
protection — modelled as securitySchemes.AdminSignedEnvelope.
The TypeScript SDK (@voidly/pay-sdk)
and the @voidly/mcp-server
package handle canonicalization and signing for you.
npx openapi-typescript https://voidly.ai/voidly-pay-openapi.yaml \
--output src/types/voidly-pay.d.tsimport type { paths } from './types/voidly-pay'
type Wallet =
paths['/v1/pay/wallet/{did}']['get']['responses']['200']['content']['application/json']
type TransferReceipt =
paths['/v1/pay/transfer']['post']['responses']['200']['content']['application/json']Generates clients in 30+ languages:
# Python
npx @openapitools/openapi-generator-cli generate \
-i https://voidly.ai/voidly-pay-openapi.yaml \
-g python -o ./voidly_pay_client
# Go
npx @openapitools/openapi-generator-cli generate \
-i https://voidly.ai/voidly-pay-openapi.yaml \
-g go -o ./voidly-pay-go \
--additional-properties=packageName=voidlypay
# Rust
npx @openapitools/openapi-generator-cli generate \
-i https://voidly.ai/voidly-pay-openapi.yaml \
-g rust -o ./voidly-pay-rs
# Java, Kotlin, Swift, C#, PHP, Ruby, etc. — see openapi-generator.techThe generated clients ship with the full schema, but do not include
canonical JSON signing. Wrap the generated transfer / escrow_open /
hire operations in your own helper that builds the envelope, signs it,
and submits.
A complete Python signing helper is included in
SPEC.md, and a runnable port lives at
voidly-ai/voidly-pay-samples/_lib/voidly_pay.py.
- Open Postman →
File → Import → URL - Paste:
https://voidly.ai/voidly-pay-postman.json - The collection ships with placeholder variables:
{{baseUrl}},{{did}},{{escrowId}},{{capabilityId}},{{hireId}},{{receiptId}}. - Set
{{baseUrl}}tohttps://api.voidly.ai. - For read endpoints, just hit Send. For writes, you need to sign the
envelope locally — Postman does not have native Ed25519, so use the
SDK to produce
{ envelope, signature }and paste into the body.
All three consume vanilla OpenAPI 3.1.
- Insomnia:
File → Import → From URL→https://voidly.ai/voidly-pay-openapi.yaml - Bruno:
Import → OpenAPI v3→ paste the URL. - Stoplight Studio:
File → Open→ paste the URL.
The YAML passes both swagger-cli and redocly lint with zero errors:
npx @apidevtools/swagger-cli validate openapi.yaml
# → openapi.yaml is valid
npx @redocly/cli lint --skip-rule no-invalid-media-type-examples openapi.yaml
# → Woohoo! Your API description is valid.The skipped rule (no-invalid-media-type-examples) is a known Redocly
quirk where examples that include a schema discriminator field —
required by Voidly's response envelope convention — are flagged as
"unevaluated properties". The schema itself does declare schema; the
rule's structural matcher misses our Error.schema property.
- Canonicalization implementation — see the envelope source.
- Signing — runtime — use
@voidly/pay-sdk(TypeScript) or the Python helper in the sample apps. - Streaming — Stage 1.16 has no SSE / WebSocket / push endpoints.
The roadmap is documented in
asyncapi.yamland ships with Stage 1.20.
Spec version follows the deployed Voidly Pay stage:
| Spec version | Stage | What changed |
|---|---|---|
1.16.0 |
1.16 — production | Initial public spec, 34 endpoints |
1.16.1 |
1.16.1 — hardened | Default 4xx/5xx responses, Error schema, OAS 3.1 nullable fix |
1.16.2 |
1.16.2 — auth hardened | Per-operation security declarations, SignedEnvelope + AdminSignedEnvelope security schemes |
Breaking changes will bump the major version (2.x.x) and ship behind
/v2/pay/* URLs alongside /v1/pay/* until v1 is retired with at least
6 months of deprecation notice.
Future specs will be added to this repo as the surface area grows:
- Voidly Atlas — censorship intelligence (incidents, evidence,
forecasts, ISP risk index, accessibility checks). Currently lives at
https://voidly.ai/api-docs— will be promoted here when the spec reaches 1.0. - Voidly Relay — E2E encrypted agent messaging (DIDs, signed
capabilities, encrypted channels). Currently in
agent-relay-protocol.md— will be split into its own OpenAPI doc.
Spec bugs, missing fields, generator failures, etc. — file an issue at github.com/voidly-ai/openapi-specs/issues.
For Voidly Pay implementation bugs (the running service) file at github.com/voidly-ai/voidly-pay/issues.
MIT — see LICENSE.
Built by Voidly Research. The Voidly platform is a censorship research network with AI-powered privacy tools — Pay is the credit-ledger layer.