# Receive Addresses (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/receive-addresses/
> Staging base URL: https://api-staging.coinbax.com

## List a user's receive addresses, newest first

`GET /api/v2/receive-addresses`

- Auth: OAuth 2.0 client credentials, scope `read:receive-addresses`
- Operation ID: `ReceiveAddressController_list_v2`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | query | string (uuid) | yes | Workspace the addresses belong to. Must be the workspace your OAuth client is bound to. |
| `userId` | query | string | yes | Your identifier for the end user whose addresses to list. |

### Example request

```bash
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:receive-addresses"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/receive-addresses?workspaceId=<workspaceId>&userId=<userId>' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** The user's receive addresses, newest first.

```json
[
  {
    "id": "0b1c6a56-4d36-4f4c-9e4b-7d5b2c0d3f11",
    "address": "0x1111111111111111111111111111111111111111",
    "network": "base",
    "label": "Rent",
    "status": "active",
    "created_at": "2026-10-05T12:00:00.000Z",
    "created_from": "plugin",
    "total_received": "0",
    "userId": "customer-123"
  }
]
```

**400** workspaceId or userId is missing or malformed

**401** Invalid or missing OAuth token

**403** Missing scope, the OAuth client is not bound to a workspace (code WORKSPACE_BINDING_REQUIRED), or workspaceId is not the workspace the client is bound to (code WORKSPACE_MISMATCH)

---

## Create a receive address

`POST /api/v2/receive-addresses`

- Auth: OAuth 2.0 client credentials, scope `write:receive-addresses`
- Operation ID: `ReceiveAddressController_create_v2`

Mints a new, unique address for the user on the given network. Every call returns a new address.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string (uuid) | yes | Workspace the address belongs to. Must be the workspace your OAuth client is bound to. |
| `userId` | string | yes | Your identifier for the end user who will receive funds. |
| `network` | enum ("base", "base-sepolia", "solana", "solana-devnet") | yes | Network to mint the address on: testnets (`base-sepolia`, `solana-devnet`) on staging, mainnets (`base`, `solana`) in production. A `solana-devnet` address is a USDC associated token account whose authority is an address derived by the receive program, so it is base58 rather than hex. `solana` answers 501: no receive program is deployed to Solana mainnet yet. |
| `label` | string | no | Optional label for the address, as plain text. Surrounding whitespace is trimmed; a blank label is stored as null. |

```json
{
  "workspaceId": "79a1ae93-68db-43b8-8217-1d7b31233ab0",
  "userId": "customer-123",
  "network": "base-sepolia",
  "label": "Rent"
}
```

### Example request

```bash
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:receive-addresses"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/receive-addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "79a1ae93-68db-43b8-8217-1d7b31233ab0",
  "userId": "customer-123",
  "network": "base-sepolia",
  "label": "Rent"
}'
```

### Responses

**201** The new receive address.

```json
{
  "id": "0b1c6a56-4d36-4f4c-9e4b-7d5b2c0d3f11",
  "address": "0x1111111111111111111111111111111111111111",
  "network": "base",
  "label": "Rent",
  "status": "active",
  "created_at": "2026-10-05T12:00:00.000Z",
  "created_from": "plugin",
  "total_received": "0",
  "userId": "customer-123"
}
```

**400** Invalid body, or network not available in this environment

**401** Invalid or missing OAuth token

**403** Missing scope, the OAuth client is not bound to a workspace (code WORKSPACE_BINDING_REQUIRED), or workspaceId is not the workspace the client is bound to (code WORKSPACE_MISMATCH)

**429** The user has created as many addresses in the last minute as the workspace allows (code RECEIVE_ADDRESS_RATE_LIMITED). Nothing was created. Retry after the number of seconds in the `Retry-After` header, also sent as `error.details.retryAfterSeconds`.

**501** No receive address can be minted on this network in this environment yet (code RECEIVE_ADDRESS_DERIVATION_NOT_AVAILABLE).

**503** The address could not be read from the chain (code RECEIVE_ADDRESS_DERIVATION_UNAVAILABLE). Nothing was created; retry.

---

## Label or freeze a receive address

`PATCH /api/v2/receive-addresses/{id}`

- Auth: OAuth 2.0 client credentials, scope `write:receive-addresses`
- Operation ID: `ReceiveAddressController_update_v2`

Send exactly one of `label` or `status: "frozen"`. Freezing is one-way.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Id of the receive address. |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | The end user who owns the address. Another user gets a 404. |
| `label` | string | no | New label, as plain text. Surrounding whitespace is trimmed; an empty or blank string, or null, clears it. |
| `status` | enum ("frozen") | no | Freeze the address. There is no unfreeze. |

```json
{
  "userId": "customer-123",
  "label": "Rent",
  "status": "frozen"
}
```

### Example request

```bash
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:receive-addresses"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X PATCH 'https://api-staging.coinbax.com/api/v2/receive-addresses/<id>' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "customer-123",
  "label": "Rent",
  "status": "frozen"
}'
```

### Responses

**200** The updated receive address.

```json
{
  "id": "0b1c6a56-4d36-4f4c-9e4b-7d5b2c0d3f11",
  "address": "0x1111111111111111111111111111111111111111",
  "network": "base",
  "label": "Rent",
  "status": "active",
  "created_at": "2026-10-05T12:00:00.000Z",
  "created_from": "plugin",
  "total_received": "0",
  "userId": "customer-123"
}
```

**400** Not exactly one of `label` or `status`, `status` is not "frozen", or the id is not a UUID

**401** Invalid or missing OAuth token

**403** Missing scope, or the OAuth client is not bound to a workspace (code WORKSPACE_BINDING_REQUIRED)

**404** No such address for this client
