---
title: "Create a subscription (URL and chains), optionally with initial addresses."
method: POST
path: "/push/subscriptions"
tags: ["Subscriptions"]
---

# Create a subscription (URL and chains), optionally with initial addresses.

`POST /push/subscriptions`

## Request

- Base URL: `https://api.blockvectra.com/v1`
- URL: `https://api.blockvectra.com/v1/push/subscriptions`
- Auth: API key in header `x-api-key`

`chains` is required and has at least one key; without it (or with an empty object) the call is 422 `chains_required` and `data.available` lists the chains open for push; there is no default chain, nothing is created and nothing is billed. A chain whose value is `{}` uses the chain default confirmations. The subscription is `online` at once; every chain starts after the chain head at creation (`start_block` is stamped by the platform, usually within a second, and is `null` until then); events from before creation are not delivered and `replay` cannot bring them (there were no matches yet), use the Data API by address. There is no verification or test message: the first message carries on-chain events. The response carries the signing `secret`, the only time it is shown. The calling key becomes the billed key; a key whose CU cap is used up can still create it; delivery pauses as soon as the key cu_cap or the account balance is exhausted and resumes without loss after a top-up or a cap increase; the condition field reflects settled usage and can lag up to one settlement period (about one hour). Optional `addresses` uses the same normalization, set semantics and admission as addresses/add (1 to 10,000 items; the creation body still must fit in 64 KiB). Creation and initial addresses commit together, or nothing is created. When omitted the subscription starts with no addresses; add more with the address endpoint. Each subscription holds at most 1,000,000 distinct addresses.

## Request body

- SubscriptionCreate
  - `url` string, required: https, port 443, a host name (no IP literal), no userinfo or fragment; stored and returned normalized.
  - `addresses` AddressInput[]: Optional initial addresses; the complete creation body must fit in 64 KiB. Added atomically with the subscription.
  - `chains` object, required

## Response `201`

Created.

- SubscriptionCreated
  - `id` integer, required: The subscription id: the one number that identifies a subscription everywhere (PostgreSQL integer identity, fits u32, never reused). A plain JSON integer in bodies, decimal digits in the path.
  - `url` string, required: https, port 443, a host name (no IP literal), no userinfo or fragment; stored and returned normalized.
  - `status` 'online' | 'offline', required: online listens and delivers; offline does not listen (addresses unloaded, no matching, delivery or address fee) and keeps its whole configuration, and can go online again at any time. Change it with PATCH; the system also sets offline when the subscription expires (a chain failed for the expiry window, currently 7 days, and no other chain delivered inside it).
  - `key_id` string, required
  - `address_count` integer, required: Distinct addresses of this subscription; additions cannot exceed 1,000,000. Existing oversized subscriptions can remove addresses and resend existing addresses.
  - `applied_version` integer, required: Address and chain changes of this subscription up to this version are applied on every chain; compare with change_version returned by add, remove and PATCH (a counter of this subscription only).
  - `chains` object, required
  - `created_at` string, required

## Other responses

- `400`: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.
- `409`: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.
- `422`: chain_not_available, chains_required, confirmations_out_of_range, or destination_not_allowed.
- `default`: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.

---

[API](https://skmtc.dev/blockvectra/apis/blockvectra-push-api.md) · [All operations](https://skmtc.dev/blockvectra/apis/blockvectra-push-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blockvectra/apis/blockvectra-push-api/revisions/396dd7621c54?raw)