Canonical machine-readable specifications for the Voidly platform. Use them to generate typed clients, populate Postman, build mocks, or validate your own server implementation.

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:

1. Drops keys with null / undefined values
2. Sorts keys lexicographically
3. UTF-8 encodes without whitespace (per RFC 8785 JSON Canonicalization Scheme)
4. Computes SHA-256 of the canonical bytes
5. 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.ts

import 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.tech

The 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.

1. Open Postman → File → Import → URL
2. Paste: https://voidly.ai/voidly-pay-postman.json
3. The collection ships with placeholder variables: {{baseUrl}}, {{did}}, {{escrowId}}, {{capabilityId}}, {{hireId}}, {{receiptId}}.
4. Set {{baseUrl}} to https://api.voidly.ai.
5. 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.yaml and ships with Stage 1.20.

Spec version follows the deployed Voidly Pay stage:

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.