Documentation

Query Parameters

Onibloc will forward every query parameter prefixed with oni_ from the paywall link to the redirect URL (up to 10). It also appends a unique oni_purchase_session_id.

Make your app point your customer to:
https://onibloc.com/paywall/abc123?oni_customer_ref=123&oni_order_id=abc
Customer pays.
Customer gets redirected to:
https://your-product.com/private?oni_customer_ref=123&oni_order_id=abc&oni_purchase_session_id=xyz

Event object

When payment is settled, your webhook receives this JSON payload:

{
  "id": "evt_01HR6Y9S8P7E3N6D4Q2A1B0C",
  "type": "payment.settled",
  "created": "2026-04-10T12:34:56.789Z",
  "data": {
    "paywallId": "paywall_abc123",
    "purchaseSessionId": "session_xyz789",
    "invoicePaymentHash": "6f5d...c2a1",
    "amountSats": 2100,
    "payoutStatus": "forwarded",
    "settledAt": "2026-04-10T12:34:55.123Z",
    "forwardedOniQueryParams": [
      { "key": "oni_customer_ref", "value": "123" },
      { "key": "oni_order_id", "value": "abc" }
    ]
  }
}

API

Programmatic access for seller integrations, including the OpenAPI spec and paywall management endpoints.

OpenAPI

The machine-readable API spec is available at /api/openapi.json.

curl "https://onibloc.com/api/openapi.json"

Use this file with Swagger UI, Scalar, Postman import, or any OpenAPI-compatible client generator.

List paywalls

Use your seller API key to fetch all paywalls attached to your account.

Endpoint: GET /api/paywalls

Required scope: read:paywalls

Auth headers: Authorization: Bearer <api_key> or x-api-key: <api_key>

curl -X GET "https://onibloc.com/api/paywalls" \
  -H "Authorization: Bearer obk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "paywalls": [
    {
      "id": "paywall_abc123",
      "sellerId": "seller_123",
      "walletId": "wallet_456",
      "productName": "Premium article",
      "description": "One-time access",
      "priceSats": 1500,
      "destinationUrl": "https://your-product.com/premium/article-1",
      "webhookUrl": "https://your-api.com/webhooks/onibloc",
      "themeColor": "#0f172a",
      "active": true,
      "createdAt": "2026-04-24T10:20:30.000Z"
    }
  ]
}

Error codes: 401 (missing/invalid key), 403 (missing scope), 500 (server error).

Create paywall

Use your seller API key to connect a wallet and create a paywall in one request.

Endpoint: POST /api/paywalls

Required scope: write:paywalls

Auth headers: Authorization: Bearer <api_key> or x-api-key: <api_key>

Wallet input: pass a single wallet string. Use either a Lightning Address like hello@getalby.com or an NWC connection string starting with nostr+walletconnect://.

curl -X POST "https://onibloc.com/api/paywalls" \
  -H "Authorization: Bearer obk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "hello@getalby.com",
    "productName": "Premium article",
    "description": "One-time access",
    "priceSats": 1500,
    "destinationUrl": "https://your-product.com/premium/article-1",
    "webhookUrl": "https://your-api.com/webhooks/onibloc",
    "themeColor": "#0f172a",
    "active": true
  }'

curl -X POST "https://onibloc.com/api/paywalls" \
  -H "Authorization: Bearer obk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "nostr+walletconnect://wallet?relay=wss%3A%2F%2Frelay.example.com&secret=sekret",
    "productName": "Premium article",
    "priceSats": 1500,
    "destinationUrl": "https://your-product.com/premium/article-1"
  }'

{
  "paywall": {
    "id": "paywall_abc123",
    "sellerId": "seller_123",
    "walletId": "wallet_456",
    "productName": "Premium article",
    "description": "One-time access",
    "priceSats": 1500,
    "destinationUrl": "https://your-product.com/premium/article-1",
    "webhookUrl": "https://your-api.com/webhooks/onibloc",
    "themeColor": "#0f172a",
    "active": true,
    "createdAt": "2026-04-24T10:20:30.000Z"
  }
}

Error codes: 400 (invalid body or wallet input), 401 (missing/invalid key), 403 (missing scope), 404 (seller not found), 500 (server error).