{ "openapi": "3.0.4", "info": { "title": "send21 API", "description": "Non-custodial payment drafts and pay links for BTC (on-chain and Lightning), USDC, USDT, EURC, SOL and ETH, for humans and AI agents. send21 never holds keys or funds. It prepares payment instructions that the payer signs in their own wallet: one QR payment from any wallet, or a batched template for PSBT wallets (Bitcoin Core, Sparrow, Electrum) and batching wallets such as Safe. AI agents authenticate with scoped API keys (Authorization: Bearer s21_...) and get idempotent creation, batch operations, recurring templates, and HMAC-signed webhooks (see the Webhooks section for events, payloads and signature checks). MCP server: /mcp. Machine-readable overview: /llms.txt. Integration questions: integration@send21.io. Account or payment issues: support@send21.io", "contact": { "name": "send21 integration support", "email": "integration@send21.io" }, "version": "v1" }, "paths": { "/api/v1/address-book": { "get": { "tags": [ "AddressBook" ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "AddressBook" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/address-book/{id}": { "put": { "tags": [ "AddressBook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddressBookUpsertRequest" } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "AddressBook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/api-keys": { "get": { "tags": [ "ApiKeys" ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "ApiKeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/api-keys/{id}": { "delete": { "tags": [ "ApiKeys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/register/begin": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterBeginRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RegisterBeginRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RegisterBeginRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/register/complete": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCompleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RegisterCompleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RegisterCompleteRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/login/begin": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/login/complete": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCompleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LoginCompleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LoginCompleteRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/register": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRegisterRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PasswordRegisterRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PasswordRegisterRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/register/complete": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/change": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/forgot": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordForgotRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PasswordForgotRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PasswordForgotRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/forgot/complete": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordForgotCompleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PasswordForgotCompleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PasswordForgotCompleteRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/login": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordLoginRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PasswordLoginRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PasswordLoginRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/password/login/complete": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EmailCodeCompleteRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/me": { "get": { "tags": [ "Auth" ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/account": { "delete": { "tags": [ "Auth" ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/totp/setup": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/totp/enable": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/auth/totp/disable": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/checkout/{token}": { "get": { "tags": [ "Checkout" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/checkout/{token}/select": { "post": { "tags": [ "Checkout" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSelectRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CheckoutSelectRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CheckoutSelectRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/checkout/{token}/status": { "get": { "tags": [ "Checkout" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/demo/config": { "get": { "tags": [ "Demo" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoConfigResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoConfigResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoConfigResponse" } } } } } } }, "/api/v1/demo/drafts": { "post": { "tags": [ "Demo" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDemoDraftRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDemoDraftRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDemoDraftRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } } } } } } }, "/api/v1/demo/drafts/{id}": { "get": { "tags": [ "Demo" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoDraftResponse" } } } } } } }, "/api/v1/drafts": { "post": { "tags": [ "Drafts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDraftRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDraftRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DraftResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } } } } }, "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/DraftStatus" } }, { "name": "network", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentNetwork" } }, { "name": "method", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentMethod" } }, { "name": "currency", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentCurrency" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/batch": { "post": { "tags": [ "Drafts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateDraftsRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BatchCreateDraftsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/BatchCreateDraftsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDraftResult" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDraftResult" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDraftResult" } } } } } } } }, "/api/v1/drafts/{id}": { "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/status": { "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/cancel": { "post": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/accept-received": { "post": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/requote": { "post": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/fees": { "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/pdf": { "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/drafts/{id}/tx-template": { "get": { "tags": [ "Drafts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/fees/schedule": { "get": { "tags": [ "Fees" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/FeeScheduleResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FeeScheduleResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FeeScheduleResponse" } } } } } } }, "/api/v1/fees/accrued": { "get": { "tags": [ "Fees" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/AccruedFeesResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AccruedFeesResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AccruedFeesResponse" } } } } } } }, "/api/v1/fees/accrued/settle": { "post": { "tags": [ "Fees" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleAccruedFeesRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SettleAccruedFeesRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SettleAccruedFeesRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DraftResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } } } } } }, "/api/v1/payment-requests": { "post": { "tags": [ "PaymentRequests" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequestRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequestRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequestRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } } } }, "get": { "tags": [ "PaymentRequests" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestResponse" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestResponse" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } } } } } }, "/api/v1/payment-requests/{id}": { "get": { "tags": [ "PaymentRequests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/payment-requests/{id}/cancel": { "post": { "tags": [ "PaymentRequests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/rates": { "get": { "tags": [ "Rates" ], "parameters": [ { "name": "ccy", "in": "query", "schema": { "type": "string", "default": "USD" } }, { "name": "asset", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentCurrency" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/recurring-templates": { "get": { "tags": [ "RecurringTemplates" ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "RecurringTemplates" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringTemplateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringTemplateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateRecurringTemplateRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/recurring-templates/{id}/pause": { "post": { "tags": [ "RecurringTemplates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/recurring-templates/{id}/resume": { "post": { "tags": [ "RecurringTemplates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/recurring-templates/{id}": { "delete": { "tags": [ "RecurringTemplates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/suggestions": { "post": { "tags": [ "Suggestions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SuggestionRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SuggestionRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "AccruedFeesResponse": { "type": "object", "properties": { "outstandingUsd": { "type": "number", "format": "double" }, "draftCount": { "type": "integer", "format": "int32" }, "oldestAccruedAt": { "type": "string", "format": "date-time", "nullable": true }, "maxOutstandingUsd": { "type": "number", "format": "double" }, "maxAgeDays": { "type": "integer", "format": "int32" }, "blocked": { "type": "boolean" }, "activeSettlementDraftId": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false }, "AddressBookUpsertRequest": { "type": "object", "properties": { "label": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "verified": { "type": "boolean" }, "direction": { "$ref": "#/components/schemas/AddressDirection" } }, "additionalProperties": false }, "AddressDirection": { "enum": [ "Sending", "Receiving" ], "type": "string" }, "AmountMismatchInfo": { "type": "object", "properties": { "txId": { "type": "string", "nullable": true }, "expectedBaseUnits": { "type": "integer", "format": "int64" }, "receivedBaseUnits": { "type": "integer", "format": "int64" }, "differenceBaseUnits": { "type": "integer", "format": "int64" }, "receivedFormatted": { "type": "string", "nullable": true }, "differenceFormatted": { "type": "string", "nullable": true }, "confirmations": { "type": "integer", "format": "int32" }, "detectedAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "AssertionResponse": { "required": [ "authenticatorData", "clientDataJSON", "signature" ], "type": "object", "properties": { "authenticatorData": { "type": "string", "format": "byte", "nullable": true }, "signature": { "type": "string", "format": "byte", "nullable": true }, "clientDataJSON": { "type": "string", "format": "byte", "nullable": true }, "userHandle": { "type": "string", "format": "byte", "nullable": true } }, "additionalProperties": false }, "AttestationResponse": { "required": [ "attestationObject", "clientDataJSON", "transports" ], "type": "object", "properties": { "attestationObject": { "type": "string", "format": "byte", "nullable": true }, "clientDataJSON": { "type": "string", "format": "byte", "nullable": true }, "transports": { "type": "array", "items": { "$ref": "#/components/schemas/AuthenticatorTransport" } } }, "additionalProperties": false }, "AuthenticationExtensionsClientOutputs": { "type": "object", "properties": { "example.extension.bool": { "type": "boolean", "nullable": true }, "appid": { "type": "boolean" }, "exts": { "type": "array", "items": { "type": "string" }, "nullable": true }, "uvm": { "type": "array", "items": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "nullable": true }, "credProps": { "$ref": "#/components/schemas/CredentialPropertiesOutput" }, "prf": { "$ref": "#/components/schemas/AuthenticationExtensionsPRFOutputs" }, "largeBlob": { "$ref": "#/components/schemas/AuthenticationExtensionsLargeBlobOutputs" }, "credProtect": { "$ref": "#/components/schemas/CredentialProtectionPolicy" } }, "additionalProperties": false }, "AuthenticationExtensionsLargeBlobOutputs": { "type": "object", "properties": { "supported": { "type": "boolean" }, "blob": { "type": "string", "format": "byte", "nullable": true }, "written": { "type": "boolean" } }, "additionalProperties": false }, "AuthenticationExtensionsPRFOutputs": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "results": { "$ref": "#/components/schemas/AuthenticationExtensionsPRFValues" } }, "additionalProperties": false }, "AuthenticationExtensionsPRFValues": { "required": [ "first" ], "type": "object", "properties": { "first": { "type": "string", "format": "byte", "nullable": true }, "second": { "type": "string", "format": "byte", "nullable": true } }, "additionalProperties": false }, "AuthenticatorAssertionRawResponse": { "required": [ "clientExtensionResults", "id", "rawId", "type" ], "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "rawId": { "type": "string", "format": "byte" }, "response": { "$ref": "#/components/schemas/AssertionResponse" }, "type": { "$ref": "#/components/schemas/PublicKeyCredentialType" }, "extensions": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" }, "clientExtensionResults": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" } }, "additionalProperties": false }, "AuthenticatorAttestationRawResponse": { "required": [ "clientExtensionResults", "id", "rawId", "response", "type" ], "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "rawId": { "type": "string", "format": "byte" }, "type": { "$ref": "#/components/schemas/PublicKeyCredentialType" }, "response": { "$ref": "#/components/schemas/AttestationResponse" }, "extensions": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" }, "clientExtensionResults": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" } }, "additionalProperties": false }, "AuthenticatorTransport": { "enum": [ "Usb", "Nfc", "Ble", "SmartCard", "Hybrid", "Internal" ], "type": "string" }, "BatchCreateDraftsRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDraftItem" }, "nullable": true } }, "additionalProperties": false }, "BatchDraftItem": { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/CreateDraftRequest" }, "idempotencyKey": { "type": "string", "nullable": true } }, "additionalProperties": false }, "BatchDraftResult": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "draft": { "$ref": "#/components/schemas/DraftResponse" }, "error": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CheckoutSelectRequest": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "method": { "$ref": "#/components/schemas/PaymentMethod" } }, "additionalProperties": false }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "CreateDemoDraftRequest": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" } }, "additionalProperties": false }, "CreateDraftRequest": { "type": "object", "properties": { "receiverAddress": { "type": "string", "nullable": true }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "amountSats": { "type": "integer", "format": "int64", "nullable": true }, "fiatCurrency": { "type": "string", "nullable": true }, "fiatAmount": { "type": "number", "format": "double", "nullable": true }, "senderAddress": { "type": "string", "nullable": true }, "bolt11": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "expiryHours": { "type": "integer", "format": "int32", "nullable": true }, "requiredConfirmations": { "type": "integer", "format": "int32", "nullable": true }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "singleOutput": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "CreatePaymentRequestRequest": { "type": "object", "properties": { "fiatCurrency": { "type": "string", "nullable": true }, "fiatAmount": { "type": "number", "format": "double" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestOptionDto" }, "nullable": true }, "orderId": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "expiryHours": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "CreateRecurringTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "interval": { "$ref": "#/components/schemas/RecurrenceInterval" }, "firstRunAt": { "type": "string", "format": "date-time", "nullable": true }, "draft": { "$ref": "#/components/schemas/CreateDraftRequest" } }, "additionalProperties": false }, "CreateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "CredentialPropertiesOutput": { "type": "object", "properties": { "rk": { "type": "boolean" }, "authenticatorDisplayName": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CredentialProtectionPolicy": { "enum": [ "UserVerificationOptional", "UserVerificationOptionalWithCredentialIdList", "UserVerificationRequired" ], "type": "string" }, "DemoConfigResponse": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "expiryMinutes": { "type": "integer", "format": "int32" }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/DemoNetworkInfo" }, "nullable": true } }, "additionalProperties": false }, "DemoDraftResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "receiverAddress": { "type": "string", "nullable": true }, "amountBaseUnits": { "type": "integer", "format": "int64" }, "amountFormatted": { "type": "string", "nullable": true }, "tokenAddress": { "type": "string", "nullable": true }, "paymentUri": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/DraftStatus" }, "paidTxId": { "type": "string", "nullable": true }, "confirmations": { "type": "integer", "format": "int32" }, "requiredConfirmations": { "type": "integer", "format": "int32" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "DemoNetworkInfo": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "currencies": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentCurrency" }, "nullable": true } }, "additionalProperties": false }, "DraftResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "receiverAddress": { "type": "string", "nullable": true }, "senderAddress": { "type": "string", "nullable": true }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "amountSats": { "type": "integer", "format": "int64" }, "amountBtc": { "type": "string", "nullable": true }, "fiatCurrency": { "type": "string", "nullable": true }, "fiatAmount": { "type": "number", "format": "double", "nullable": true }, "quote": { "$ref": "#/components/schemas/QuoteInfo" }, "platformFeeSats": { "type": "integer", "format": "int64" }, "platformFeeAddress": { "type": "string", "nullable": true }, "platformFee": { "$ref": "#/components/schemas/PlatformFeeInfo" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "bolt11": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/DraftStatus" }, "paidTxId": { "type": "string", "nullable": true }, "requiredConfirmations": { "type": "integer", "format": "int32" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sek": { "$ref": "#/components/schemas/SekValueInfo" }, "feeOutputs": { "type": "array", "items": { "$ref": "#/components/schemas/FeeOutputInfo" }, "nullable": true }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "tokenAddress": { "type": "string", "nullable": true }, "feeAccrued": { "type": "boolean" }, "isFeeSettlement": { "type": "boolean" }, "paymentUri": { "type": "string", "nullable": true }, "amountMismatch": { "$ref": "#/components/schemas/AmountMismatchInfo" }, "lightningAddress": { "type": "string", "nullable": true }, "lightningConfirmable": { "type": "boolean" } }, "additionalProperties": false }, "DraftStatus": { "enum": [ "AwaitingPayment", "Seen", "Confirmed", "Expired", "Cancelled" ], "type": "string" }, "EmailCodeCompleteRequest": { "type": "object", "properties": { "ceremonyId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FeeOutputInfo": { "type": "object", "properties": { "recipient": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "sats": { "type": "integer", "format": "int64" }, "sharePercent": { "type": "number", "format": "double" } }, "additionalProperties": false }, "FeeScheduleResponse": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/FeeTierDto" }, "nullable": true }, "minFeeUsd": { "type": "number", "format": "double" }, "maxFeeUsd": { "type": "number", "format": "double" }, "dustLimitSats": { "type": "integer", "format": "int64" }, "pricedIn": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FeeTierDto": { "type": "object", "properties": { "upToUsd": { "type": "number", "format": "double", "nullable": true }, "percent": { "type": "number", "format": "double" } }, "additionalProperties": false }, "LoginCompleteRequest": { "type": "object", "properties": { "ceremonyId": { "type": "string", "format": "uuid" }, "credential": { "$ref": "#/components/schemas/AuthenticatorAssertionRawResponse" }, "totpCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PasswordChangeRequest": { "type": "object", "properties": { "currentPassword": { "type": "string", "nullable": true }, "newPassword": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PasswordForgotCompleteRequest": { "type": "object", "properties": { "ceremonyId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "nullable": true }, "newPassword": { "type": "string", "nullable": true }, "totpCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PasswordForgotRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PasswordLoginRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "totpCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PasswordRegisterRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PaymentCurrency": { "enum": [ "Btc", "Usdc", "Usdt", "Eurc", "Sol", "Eth" ], "type": "string" }, "PaymentMethod": { "enum": [ "MultiOutput", "Lightning" ], "type": "string" }, "PaymentNetwork": { "enum": [ "Mainnet", "Testnet4", "Signet", "Regtest", "Solana", "SolanaDevnet", "Ethereum", "EthereumSepolia", "Base", "BaseSepolia", "Arbitrum", "ArbitrumSepolia", "Polygon", "PolygonAmoy" ], "type": "string" }, "PaymentRequestFeeInfo": { "type": "object", "properties": { "percent": { "type": "number", "format": "double", "nullable": true }, "feeUsd": { "type": "number", "format": "double", "nullable": true }, "feeBaseUnits": { "type": "integer", "format": "int64" }, "feeAmount": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "waived": { "type": "boolean" }, "settledAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "PaymentRequestOptionDto": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "network": { "$ref": "#/components/schemas/PaymentNetwork" }, "address": { "type": "string", "nullable": true }, "method": { "$ref": "#/components/schemas/PaymentMethod" } }, "additionalProperties": false }, "PaymentRequestResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "shareToken": { "type": "string", "nullable": true }, "payPath": { "type": "string", "nullable": true }, "orderId": { "type": "string", "nullable": true }, "fiatCurrency": { "type": "string", "nullable": true }, "fiatAmount": { "type": "number", "format": "double" }, "memo": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/PaymentRequestStatus" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestOptionDto" }, "nullable": true }, "activeDraftId": { "type": "string", "format": "uuid", "nullable": true }, "draftStatus": { "$ref": "#/components/schemas/DraftStatus" }, "fee": { "$ref": "#/components/schemas/PaymentRequestFeeInfo" }, "amountMismatch": { "$ref": "#/components/schemas/AmountMismatchInfo" } }, "additionalProperties": false }, "PaymentRequestStatus": { "enum": [ "Open", "Completed", "Cancelled", "Expired" ], "type": "string" }, "PlatformFeeInfo": { "type": "object", "properties": { "percent": { "type": "number", "format": "double", "nullable": true }, "usd": { "type": "number", "format": "double", "nullable": true }, "sats": { "type": "integer", "format": "int64" }, "waived": { "type": "boolean" }, "usdPerBtc": { "type": "number", "format": "double", "nullable": true }, "rateSource": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicKeyCredentialType": { "enum": [ "PublicKey", "Invalid" ], "type": "string" }, "QuoteInfo": { "type": "object", "properties": { "source": { "type": "string", "nullable": true }, "rate": { "type": "number", "format": "double" }, "lockedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "RecurrenceInterval": { "enum": [ "Daily", "Weekly", "Monthly" ], "type": "string" }, "RegisterBeginRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true } }, "additionalProperties": false }, "RegisterCompleteRequest": { "type": "object", "properties": { "ceremonyId": { "type": "string", "format": "uuid" }, "credential": { "$ref": "#/components/schemas/AuthenticatorAttestationRawResponse" }, "credentialName": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SekValueInfo": { "type": "object", "properties": { "ratePerBtc": { "type": "number", "format": "double" }, "rateSource": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double", "nullable": true }, "platformFee": { "type": "number", "format": "double", "nullable": true }, "vatRatePercent": { "type": "number", "format": "double", "nullable": true }, "platformFeeVat": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false }, "SettleAccruedFeesRequest": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "network": { "$ref": "#/components/schemas/PaymentNetwork" } }, "additionalProperties": false }, "SuggestionRequest": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "additionalProperties": false }, "TotpCodeRequest": { "type": "object", "properties": { "code": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "ApiKey": { "type": "http", "description": "AI-agent API key (Authorization: Bearer s21_...). Humans use passkey session cookies instead.", "scheme": "bearer", "bearerFormat": "s21_..." } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "AddressBook" }, { "name": "ApiKeys" }, { "name": "Auth" }, { "name": "Checkout" }, { "name": "Demo" }, { "name": "Drafts" }, { "name": "Fees" }, { "name": "PaymentRequests" }, { "name": "Rates" }, { "name": "RecurringTemplates" }, { "name": "Suggestions" }, { "name": "Webhooks", "description": "**send21 calls your server when a draft changes.** Register an endpoint with `POST /api/v1/webhooks`\n(scope `webhooks:manage`) and pick the events you want. The response contains the signing secret\nonce; store it. Send a signed test event any time with `POST /api/v1/webhooks/{id}/test`.\n\n### Delivery\n\nA `POST` to your URL with `Content-Type: application/json` and this body:\n\n```json\n{ \"event\": \"draft.confirmed\", \"data\": { ... } }\n```\n\n| Header | Meaning |\n|---|---|\n| `X-Send21-Event` | The event type, same as `event` in the body. |\n| `X-Send21-Delivery` | Unique delivery id. Retries reuse it, so use it to ignore duplicates. |\n| `X-Send21-Signature` | `sha256=` followed by the lowercase hex HMAC-SHA256 of the raw body, keyed with your secret. |\n\nAny 2xx response counts as delivered. Anything else, or no answer within 15 seconds, is retried\nafter 1, 2, 4, 8 minutes and so on, up to 8 attempts. Deliveries can arrive out of order.\n\n### Verifying the signature\n\nCompute the HMAC over the raw request bytes, before parsing the JSON, and compare in constant time.\n`timingSafeEqual` throws when the lengths differ, so check the header first and answer 401 when it\nis missing or wrong:\n\n```js\nconst expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));\nconst received = Buffer.from(String(req.headers['x-send21-signature'] ?? ''));\nconst ok = received.length === expected.length && crypto.timingSafeEqual(received, expected);\nif (!ok) return res.status(401).end();\n```\n\n### Events\n\n| Event | When |\n|---|---|\n| `draft.created` | A draft was created: by you, an API key, a recurring template, or a payer picking a currency on a pay link. |\n| `draft.seen` | A payment for the draft was seen, but is not confirmed yet. Also sent when you accept a payment with a different amount (`acceptedByOwner: true`); `draft.confirmed` follows once that transfer has the required confirmations. |\n| `draft.confirmed` | The payment reached the required confirmations. For Lightning: the provider confirmed it with a valid preimage. |\n| `draft.amount_mismatch` | A transfer within 10% of the billed amount arrived, but not the exact amount. It does not pay the draft until you accept it with `POST /api/v1/drafts/{id}/accept-received`. |\n| `draft.expired` | The draft expired without payment. |\n| `draft.cancelled` | The draft was cancelled. |\n| `test` | Sent by the test endpoint. `data` has `message` and `occurredAt`. |\n\n### Payload of draft.seen, draft.confirmed, draft.amount_mismatch and draft.expired\n\nAmounts ending in `Sats` are base units of the sent asset: 8 decimals for BTC, 6 for USDC, USDT and\nEURC, 9 for SOL and ETH (ETH amounts are in gwei). `txId` is the transaction id or signature; for Lightning it is the payment hash. For native ETH\nfound by the balance fallback from a smart-wallet transfer, it is `block-`.\n`receivedAmountSats` and `receivedAmount` are set only when the amount differs from the billed amount,\nincluding on the `draft.confirmed` of an accepted short or over payment, so you can record what arrived.\n`paymentRequestId` and `orderId` are set for pay-link payments.\n\n```json\n{\n \"event\": \"draft.amount_mismatch\",\n \"data\": {\n \"draftId\": \"3f6c2a9e-5d1b-4c8e-9a7f-2b4d6e8f0a1c\",\n \"status\": \"AwaitingPayment\",\n \"txId\": \"5KqZ9bQ...\",\n \"confirmations\": 1,\n \"receivedAmountSats\": 49250000,\n \"receivedAmount\": \"49.250000\",\n \"sentCurrency\": \"USDC\",\n \"network\": \"Solana\",\n \"amountSats\": 50000000,\n \"sentAmount\": \"50.000000\",\n \"fiatCurrency\": \"EUR\",\n \"fiatAmount\": 46.00,\n \"conversionRate\": 0.92,\n \"rateSource\": \"coinbase\",\n \"platformFee\": {\n \"accrued\": true, \"waived\": false, \"percent\": 0.39, \"feeUsd\": 0.20,\n \"feeBaseUnits\": 195000, \"feeAmount\": \"0.195000\", \"currency\": \"USDC\"\n },\n \"paymentRequestId\": \"8d1e4b7a-0c2f-4e6d-b3a9-7f5c1e2d4a6b\",\n \"orderId\": \"ORDER-1042\",\n \"occurredAt\": \"2026-10-06T08:22:22Z\"\n }\n}\n```\n\n### Payload of draft.created and draft.cancelled\n\n`draft.created` has `draftId`, `amountSats`, `network` and `occurredAt`; pay-link drafts add\n`paymentRequestId`, `orderId` and `currency`. `draft.cancelled` has `draftId`, `status`, `network`,\n`amountSats`, `paymentRequestId` and `occurredAt`." } ] }