Coinbax API

Receive Addresses

View as Markdown

List a user's receive addresses, newest first

GET/api/v2/receive-addressesOAuth 2.0 client credentials

Query 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.
array of ReceiveAddressResponseDto
  • 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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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();

Create a receive address

POST/api/v2/receive-addressesOAuth 2.0 client credentials

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

Request body

  • workspaceIdstring (uuid)required

    Workspace the address belongs to. Must be the workspace your OAuth client is bound to.

  • userIdstringrequired

    Your identifier for the end user who will receive funds.

  • networkenumrequired"base" · "base-sepolia" · "solana" · "solana-devnet"

    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.

  • labelstring

    Optional label for the address, as plain text. Surrounding whitespace is trimmed; a blank label is stored as null.

Responses

201The new receive address.
  • 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"
}
400Invalid body, or network not available in this environment
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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"
  }
}
429The 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`.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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"
  }
}
501No receive address can be minted on this network in this environment yet (code RECEIVE_ADDRESS_DERIVATION_NOT_AVAILABLE).
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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"
  }
}
503The address could not be read from the chain (code RECEIVE_ADDRESS_DERIVATION_UNAVAILABLE). Nothing was created; retry.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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: "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"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/receive-addresses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "workspaceId": "79a1ae93-68db-43b8-8217-1d7b31233ab0",
    "userId": "customer-123",
    "network": "base-sepolia",
    "label": "Rent"
  }),
});
const result = await response.json();

Label or freeze a receive address

PATCH/api/v2/receive-addresses/{id}OAuth 2.0 client credentials

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

Path parameters

  • idstring (uuid)required

    Id of the receive address.

Request body

  • userIdstringrequired

    The end user who owns the address. Another user gets a 404.

  • labelstring

    New label, as plain text. Surrounding whitespace is trimmed; an empty or blank string, or null, clears it.

  • statusenum"frozen"

    Freeze the address. There is no unfreeze.

Responses

200The updated receive address.
  • 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"
}
400Not exactly one of `label` or `status`, `status` is not "frozen", or the id is not a UUID
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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, or the OAuth client is not bound to a workspace (code WORKSPACE_BINDING_REQUIRED)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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"
  }
}
404No such address for this client
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `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
        object
      • array of object
        array of object
        object
      • string
        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: "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"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/receive-addresses/<id>', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "userId": "customer-123",
    "label": "Rent",
    "status": "frozen"
  }),
});
const result = await response.json();