---
title: "Add addresses"
method: POST
path: "/buckets/{bucket}/addresses"
tags: ["Buckets"]
---

# Add addresses

`POST /buckets/{bucket}/addresses`

## Request

- Base URL: `https://sochain.com/api/v3`
- URL: `https://sochain.com/api/v3/buckets/{bucket}/addresses`
- Auth: API key in header `API-KEY`

Up to 1,000 per call and 10,000 per bucket, up to 1,000,000 transactions of history across the bucket, and at most 100,000 from any one address. Every address gets a result; the bucket is complete when the call returns. If an address webhook watches the bucket, new addresses also count toward your plan's watched addresses.

## Path parameters

- `bucket` string, required: Letters, numbers, - and _, up to 64 characters. Unique within your account.

## Request body

- AddressList
  - `addresses` string[], required

## Response `200`

Success.

- object
  - `status` 'success', required
  - `data` BucketAddResult, required
    - `bucket` string, required: Letters, numbers, - and _, up to 64 characters. Unique within your account.
    - `version` integer, required
    - `added` integer, required
    - `already_member` integer, required
    - `rejected` object[], required
      - `address` string, required
      - `reason` 'wrong_network' | 'invalid' | 'too_heavy', required: too_heavy: the address alone has more than 100,000 transactions of history, or adding it would take the bucket past 1,000,000.
      - `error` string: Details, e.g. how many transactions a too_heavy address has.

## Other responses

- `400`: A bad parameter or body; the message says which.
- `401`: An invalid key, no key where one is needed (buckets, webhooks, /account_info), a locked account or expired plan, or both the month's requests and the keyless rate used up. Kept as 401, with this message, for v3 compatibility.
- `403`: A read-only key, or a change past your plan's limits: data.error_message says which.
- `404`: Not found.
- `413`: A body over the limit: 256 KB where a call carries addresses or transaction IDs, 64 KB otherwise.
- `415`: A body that isn't JSON: send it with Content-Type: application/json.
- `429`: Address changes are paced: up to 10,000 accepted changes a second per account on each network, within a network-wide cap. Wait the Retry-After seconds and send the same call again.
- `503`: Briefly unavailable; retry with backoff. May carry Retry-After.

---

[API](https://skmtc.dev/sochain/apis/sochain-api.md) · [All operations](https://skmtc.dev/sochain/apis/sochain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sochain/apis/sochain-api/revisions/80682797b38f?raw)