List a user's receive addresses, newest first
/api/v2/receive-addressesOAuth 2.0 client credentialsQuery parameters
- workspaceIdstring (uuid)required
Workspace the addresses belong to. Must be the workspace your OAuth client is bound to.
- userIdstringrequired
Your identifier for the end user whose addresses to list.
Responses
200The user's receive addresses, newest first.
- idstring (uuid)required
Id of the receive address.
- addressstringrequired
The address payers send funds to.
- networkenumrequired"base" · "base-sepolia" · "solana" · "solana-devnet"
Network the address was minted on.
- labelstringrequired
Your label for the address, or null when none is set.
- statusenumrequired"active" · "frozen"
`active`, or `frozen` once the address has been frozen.
- created_atstring (date-time)required
When the address was created, as an ISO 8601 timestamp.
- created_fromenumrequired"plugin" · "admin" · "api"
Which kind of client created the address: `plugin` (the Banno plugin), `admin` (Coinbax operator tooling) or `api` (a direct integration). Set from the OAuth client, not the request. Null for addresses created before this was recorded.
- total_receivedstringrequired
Total received, as a decimal string in USDC. Deposits are not credited yet, so this is always `0`.
- userIdstringrequired
The end user the address belongs to.
[
{
"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"
}
]400workspaceId or userId is missing or malformed
- successbooleanrequired
Always `false` on an error response.
dataenumrequired
Always `null` on an error response. Present so success and error bodies share a shape.
enumnullAlways `null` on an error response. Present so success and error bodies share a shape.
metaErrorResponseMetaDtorequired
- timestampstringrequired
ISO 8601 timestamp of the response.
- requestIdstringrequired
Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.
- pathstringrequired
Request path that produced the error.
- methodstringrequired
HTTP method of the request that produced the error.
errorApiErrorDtorequired
- codestringrequired
Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.
- messagestringrequired
Human-readable description of what went wrong.
- statusCodenumberrequired
HTTP status code, repeated here so the body is self-contained.
detailsone of
Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.
object
objectarray of object
array of objectobjectstring
string
- suggestionstring
Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.
{
"success": false,
"data": null,
"meta": {
"timestamp": "2026-11-06T12:34:56.789Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"path": "/api/v1/transactions",
"method": "POST"
},
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"statusCode": 400,
"details": {
"amount": "must be a positive number"
},
"suggestion": "Use one of: base, ethereum"
}
}401Invalid or missing OAuth token
- successbooleanrequired
Always `false` on an error response.
dataenumrequired
Always `null` on an error response. Present so success and error bodies share a shape.
enumnullAlways `null` on an error response. Present so success and error bodies share a shape.
metaErrorResponseMetaDtorequired
- timestampstringrequired
ISO 8601 timestamp of the response.
- requestIdstringrequired
Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.
- pathstringrequired
Request path that produced the error.
- methodstringrequired
HTTP method of the request that produced the error.
errorApiErrorDtorequired
- codestringrequired
Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.
- messagestringrequired
Human-readable description of what went wrong.
- statusCodenumberrequired
HTTP status code, repeated here so the body is self-contained.
detailsone of
Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.
object
objectarray of object
array of objectobjectstring
string
- suggestionstring
Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.
{
"success": false,
"data": null,
"meta": {
"timestamp": "2026-11-06T12:34:56.789Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"path": "/api/v1/transactions",
"method": "POST"
},
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"statusCode": 400,
"details": {
"amount": "must be a positive number"
},
"suggestion": "Use one of: base, ethereum"
}
}403Missing 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)
- successbooleanrequired
Always `false` on an error response.
dataenumrequired
Always `null` on an error response. Present so success and error bodies share a shape.
enumnullAlways `null` on an error response. Present so success and error bodies share a shape.
metaErrorResponseMetaDtorequired
- timestampstringrequired
ISO 8601 timestamp of the response.
- requestIdstringrequired
Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.
- pathstringrequired
Request path that produced the error.
- methodstringrequired
HTTP method of the request that produced the error.
errorApiErrorDtorequired
- codestringrequired
Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.
- messagestringrequired
Human-readable description of what went wrong.
- statusCodenumberrequired
HTTP status code, repeated here so the body is self-contained.
detailsone of
Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.
object
objectarray of object
array of objectobjectstring
string
- suggestionstring
Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.
{
"success": false,
"data": null,
"meta": {
"timestamp": "2026-11-06T12:34:56.789Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"path": "/api/v1/transactions",
"method": "POST"
},
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"statusCode": 400,
"details": {
"amount": "must be a positive number"
},
"suggestion": "Use one of: base, ethereum"
}
}# 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"// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/receive-addresses?workspaceId=<workspaceId>&userId=<userId>', {
headers: {
Authorization: `Bearer ${await getPaymentsToken()}`,
},
});
const result = await response.json();