---
title: "Add a wallet's addresses from its public key"
method: POST
path: "/buckets/{bucket}/xpub"
tags: ["Buckets"]
---

# Add a wallet's addresses from its public key

`POST /buckets/{bucket}/xpub`

## Request

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

Send a wallet's extended public key and SoChain adds its used addresses on the receive and change chains, plus `spare` unused ones after the last used (default 20). The bucket is made if it doesn't exist (then network is needed). Sending the same public key again adds newly used addresses and tops the spare ones up; another wallet's key is refused (409). The public key is used for this request only and not kept: the bucket keeps addresses, positions and the key's fingerprint. A private key (xprv…) is refused. Single-key wallets (BIP44/49/84/86).

## Path parameters

- `bucket` string, required

## Request body

- object
  - `xpub` string, required: The account public key: xpub, ypub, zpub, tpub, upub, vpub, Ltub, Mtub, ttub or dgub.
  - `network` string: Needed when the bucket doesn't exist yet.
  - `type` 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh' | 'p2tr': Implied by a ypub, zpub, upub, vpub or Mtub. A plain xpub, tpub, Ltub, ttub or dgub is used for every type: say which, or leave it out and the type the wallet has used is picked (a wallet with no history yet needs it).
  - `spare` integer

## Response `200`

Filled or topped up.

- object
  - `status` 'success'
  - `data` object
    - `bucket` string
    - `network` string
    - `type` string
    - `fingerprint` string
    - `added` integer
    - `receive` object
      - `used_through` integer, nullable
      - `next` integer
      - `spare` integer
    - `change` object
      - `used_through` integer, nullable
      - `next` integer
      - `spare` integer

## Other responses

- `400`: Not a public key, a private key, the wrong network or type: data.error_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`: Read-only key, or past the plan's bucket limits.
- `409`: The bucket was filled from another public key, or with another address type.
- `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`: A fill already under way, or too many fills: wait and try 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)