Subscriptions

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

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.

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

Request body

urlstring required

https, port 443, a host name (no IP literal), no userinfo or fragment; stored and returned normalized.

addressesAddressInput[]

Optional initial addresses; the complete creation body must fit in 64 KiB. Added atomically with the subscription.

chainsobject required

Response

Created.

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

urlstring 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_idstring required
address_countinteger required

Distinct addresses of this subscription; additions cannot exceed 1,000,000. Existing oversized subscriptions can remove addresses and resend existing addresses.

applied_versioninteger 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).

chainsobject required
created_atstring required

Changes

No recorded changes to this operation across all 1 revision of this API.