---
title: "Add up to 10,000 addresses."
method: POST
path: "/push/subscriptions/{subscription_id}/addresses/add"
tags: ["Subscriptions"]
---

# Add up to 10,000 addresses.

`POST /push/subscriptions/{subscription_id}/addresses/add`

## Request

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

All or nothing: one invalid address makes the whole batch 400 (`data.invalid`, the first 100; reasons format, checksum); a batch that would take the subscription past 1,000,000 distinct addresses is 409 `limit_reached` with `data.limit: addresses_per_subscription` and `data.max: 1000000`; a batch that would take the account past its address-pair limit is also 409 `limit_reached`; neither rejection writes addresses, counters or a change version, including under concurrent additions; when the platform capacity is full the call is a synchronous 503 `service_unavailable` and nothing is written. Set semantics: an address already watched, or repeated inside the request, counts as `unchanged` (the same address in different spellings is one address), so a resend is safe. After validation no item can fail, so the outcome of each item is reported as counts. The address applies to every chain listed in `chains` of the subscription and to no other chain. Changes apply within about a second; a chain matches the new addresses from its `applied_from_block`, not retroactively (`replay` cannot bring earlier events: it re-delivers stored matches and these addresses had none; use the Data API by address). `change_version` is applied on every chain once `applied_version` of the subscription reaches it.

## Request body

- AddressBatch
  - `addresses` AddressInput[], required

## Response `200`

Applied.

- AddResult
  - `added` integer, required
  - `unchanged` integer, required
  - `address_count` integer, required: Addresses of the subscription after the call.
  - `change_version` integer, 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.
- `413`: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.
- `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)