# blocksign.red

> BlockSign is blockchain-backed signing infrastructure for API-driven document verification.

## Canonical API

- Base URL: https://api.blocksign.red/v1
- Format: JSON only
- Auth: Bearer token (API key `bsk_*` or JWT)
- MCP endpoint: https://mcp.blocksign.red/mcp
- OpenAPI spec: https://api.blocksign.red/v1/openapi.json

## Operational Notes

- Idempotent POST support (`Idempotency-Key` header)
- Webhook retries enabled (HMAC-signed, `svix-signature` header)
- Rate limiting enforced (100 req/s burst 200)
- Public verification requires no auth or account
- 402 responses include machine-readable `billing_status` + `actions` array

## What is blocksign.red?

blocksign.red is an e-signature platform with tamper-evident audit trails anchored to Bitcoin and Base (Ethereum L2). Every signed document produces a SHA-256 hash chain verified on-chain — no account needed to verify.

## Key Capabilities

- Upload PDF, plain text, or Markdown documents (max 40 pages) — text/Markdown is converted to PDF automatically
- Create signing envelopes with fields (signature, initials, text, date, checkbox)
- AI field detection (claude-haiku) — pass `fields: "auto"` and fields are placed accurately
- Send envelopes for signing via email with real-time signing ceremony
- **Anonymous prepare flow** — upload, place fields, and pay via Stripe without signing in first
- Agent-to-agent handoff: counterparty agents receive a scoped workflow token via webhook or MCP
- Agent negotiation: counter-proposals, history, and accept endpoints
- Tamper-evident audit chain (SHA-256 hash-chained, anchored on-chain)
- Public verification — anyone can verify without an account
- Webhooks with HMAC-signed delivery (svix-signature)

## Quick Start (One API Call)

```
POST /v1/agent/agreements
Authorization: Bearer bsk_agent_...
Content-Type: application/json

{
  "template": "nda",
  "variables": {
    "party_a_name": "Acme Corp",
    "party_a_email": "alice@acme.com",
    "party_b_name": "Bob Smith",
    "party_b_email": "bob@example.com",
    "jurisdiction": "Delaware"
  },
  "options": { "auto_send": true, "webhook_url": "https://my-agent.example.com/callback" }
}
```

Response includes `agreement_id`, `verification_url`, and per-signer `signing_url`.
The `webhook_url` option registers a per-agreement callback — receives `envelope.completed` with `verification_url` when all parties sign.

You can also pass raw Markdown instead of a template:

```json
{
  "document_text": "# Services Agreement\n\nBetween {{party_a}} and {{party_b}}...",
  "document_text_format": "markdown",
  "document_title": "Services Agreement",
  "signers": [
    { "name": "Alice", "email": "alice@acme.com", "fields": "auto" },
    { "name": "Bob",   "email": "bob@example.com", "fields": "auto" }
  ],
  "options": { "auto_send": true }
}
```

## Key Resources

- POST /v1/agent/agreements — one-call create + send
- POST /v1/documents — upload PDF/text/Markdown
- GET  /v1/verify/:envelope_id — public verification (no auth)
- POST /v1/webhook-endpoints — register webhook URL
- GET  /v1/templates — list contract templates

## API Endpoints

Base URL: https://api.blocksign.red

### Discovery (no auth)
- GET /llms.txt — this file
- GET /llms-full.txt — complete API reference
- GET /.well-known/mcp.json — MCP server discovery
- GET /v1/agent/instructions — structured agent instructions (JSON)
- GET /v1/openapi.json — OpenAPI 3.1 spec

### Authentication
- POST /v1/auth/sign-up — create account
- POST /v1/auth/sign-in — get JWT tokens
- POST /v1/api-keys — create API key (bsk_live_* or bsk_agent_*)
- POST /v1/auth/oauth/exchange — server-to-server OAuth token exchange (internal)

### Documents
- POST /v1/documents — upload PDF, plain text, or Markdown (multipart/form-data); pass `detect_fields=true` to get AI field placement in the response
- GET /v1/documents/:id — fetch document metadata

### AI Field Detection
- POST /v1/agent/fields/detect — run field detection on a previously uploaded text document

### Envelopes (Traditional Flow)
- POST /v1/envelopes — create envelope with signers + fields
- GET /v1/envelopes — list envelopes
- GET /v1/envelopes/:id — fetch envelope details
- POST /v1/envelopes/:id/send — dispatch signing invitations (requires Idempotency-Key)
- POST /v1/envelopes/:id/void — void an envelope

### Agent Agreements (One-Call Flow)
- POST /v1/agent/agreements — create + send in one call (template, document_text, base64, or pre-uploaded)
- GET /v1/agent/agreements/:id — unified status view
- GET /v1/agent/agreements/:id/access — get presigned download URL (24h) when completed

### Agent Negotiation
- POST /v1/agent/agreements/:id/counter — submit counter-proposal (workflow token or API key)
- GET /v1/agent/agreements/:id/history — all proposal versions
- POST /v1/agent/agreements/:id/accept — accept current terms

### Signing Ceremony
- GET /v1/sign/:token — load signing session
- POST /v1/sign/:token/consent — record signer consent
- POST /v1/sign/:token/fields — fill fields
- POST /v1/sign/:token/sign — apply signature

### Verification (no auth)
- GET /v1/verify/:envelope_id — public integrity verification

### Templates
- GET /v1/templates — list templates
- GET /v1/templates/:id_or_slug — template details
- POST /v1/templates/:slug/preview — render with variables, no PDF
- Built-in slugs: nda, services-agreement, employment-offer, contractor, sales-agreement

### Billing
- GET /v1/billing/status — plan, usage, credits, per-document pricing
- POST /v1/billing/charge — pay per-document price (card on file required)
- POST /v1/billing/credits/purchase — buy credit pack (10/50/200)
- POST /v1/billing/checkout — start subscription checkout (Stripe)

### Webhooks
- POST /v1/webhook-endpoints — register webhook URL
- Events: envelope.sent, signer.opened, signer.signed, envelope.completed, envelope.anchored, envelope.voided

## Authentication

Two methods:
1. API Key: `Authorization: Bearer bsk_live_...` (full access) or `bsk_agent_...` (scoped)
2. JWT: `Authorization: Bearer eyJ...` (from sign-in)

OAuth: sign in with Google or Microsoft (auto-creates account on first use).

Agent keys (`bsk_agent_*`) support capability scoping: `agreement.create`, `agreement.read`, `agreement.void`, `template.use`, `template.create`, `document.upload`, `billing.auto_purchase`.

Counterparty agents in a negotiation flow receive a workflow token (`bsk_wft_*`) scoped to one envelope (72h TTL). Pass it as `x-workflow-token: bsk_wft_...`.

## MCP Server

Connect via MCP protocol (2024-11-05) for tool-based interaction:
- Transport: stateless HTTP JSON-RPC at https://mcp.blocksign.red/mcp
- Discovery: GET https://mcp.blocksign.red/.well-known/mcp.json
- Auth: Authorization: Bearer bsk_agent_* on every request
- Tools (11): create_agreement, get_agreement_status, list_agreements, list_templates, verify_agreement, void_agreement, preview_template, upload_document, detect_fields, check_billing_status, purchase_credits
- Resources: agreement://{id}, template://{slug}, verification://{id}, templates://catalog
- Prompts: create_nda, review_status, explain_verification

## Pricing

- Per-document: $2.99 base (≤10 pages) + $0.50/page over 10, max 40 pages
- Credit packs: 10/$12, 50/$50, 200/$160 — never expire, flat rate per envelope
- Pro ($29/mo): 100 envelopes/month, overage via credits
- Business ($79/mo): 500 envelopes/month, overage via credits
- 402 responses include parsable `billing_status` + `actions` array with per-document cost

## Agent Payment Flow

When your agent receives HTTP 402, follow this flow:

1. **Check billing status**: `GET /v1/billing/status` — returns plan, credits remaining, `has_payment_method`, and `per_document_pricing`
2. **Parse the 402 response**: The `actions` array tells you exactly what to do — each action has a `type` (`pay_now`, `buy_credits`, `upgrade`) and an `api` endpoint
3. **Pay per-document**: `POST /v1/billing/charge { "envelope_id": "..." }` — charges the card on file ($2.99 base + $0.50/page over 10)
4. **Buy credits**: `POST /v1/billing/credits/purchase { "credits": 50 }` — flat rate per envelope, never expire
5. **Subscribe**: `POST /v1/billing/checkout { "plan": "pro" }` — returns a Stripe Checkout URL

**Auto-purchase tip**: Agent keys (`bsk_agent_*`) with the `billing.auto_purchase` capability and a card on file never receive 402 — the smallest credit pack is charged automatically when quota is exhausted.

**MCP tools**: Use `check_billing_status` and `purchase_credits` via the MCP server for the same functionality.

## Anonymous Prepare Flow (Web UI)

Users can prepare and send documents without creating an account first:

1. **Upload PDF** — client-side validation and page counting (max 40 pages, 25 MB)
2. **Place fields** — drag-and-drop signature, initials, date, text fields onto pages
3. **Review & Pay** — per-document pricing ($2.99 base + $0.50/page over 10) or subscribe ($29/mo Pro, $79/mo Business)
4. **Stripe Checkout** — anonymous payment creates or links an account automatically
5. **Auto-send** — after payment, the document is uploaded, envelope created, and invitations sent

State (PDF bytes, fields, signers) is persisted in IndexedDB to survive the Stripe redirect.

## Links

- API Reference: /llms-full.txt
- OpenAPI Spec: /v1/openapi.json
- Verification: https://blocksign.red/verify
- Documentation: https://blocksign.red/docs