Fetch/Create Custodial Wallet

POST /services/wallets

Creates a wallet for specified coin/token for that customer. If wallet already created during customer onboarding, returns the on-chain deposit wallet address for a given customer + currency.
This is the wallet address your user should send funds to.

Authentication & Required Headers

All standard partner authentication applies.

Required Headers

Header	Description
`Authorization: <token>`	Your partner authentication token.
`partnerId: <string>`	Your assigned Partner ID (e.g., `h3gbsd98jS7sSW938`). If missing, you will receive: `"Missing request header 'partnerId' for method parameter of type String'"`.

Query Parameters

All parameters must be sent in the URL query string

Name	Type	Required	Description
`customerId`	string	Yes	Unique customer identifier used across Coinme APIs.
`currency`	string	Yes	Currency symbol for the chain/asset combo. Example: `USDC_POL`. Endpoint only takes 1 token/coin at a time.
`correlationId`	string	No (recommended)	Trace ID used for debugging and support.

Successful Response (200)

{
  "data": {
    "accountId": "0837483434346836473",
    "address": "0x97dgahdgaGH79ahdga97dhG3893GGsS83322",
    "currencySymbol": "USDC_POL",
    "currencyName": "USDC_POL",
    "walletAddress": "0x97dgahdgaGH79ahdga97dhG3893GGsS83322",
    "walletId": "20399_USDC_POLYGON_TEST_444"
  },
  "errorResponse": null
}

Response Field Reference

Field	Description
`accountId`	Mirrors the `customerId` submitted in the request.
`address`	Wallet deposit address.
`walletAddress`	Same as `address`
`currencySymbol`	The chain-specific currency code, e.g. `USDC_POL`.
`currencyName`	The chain-specific currency code
`walletId`	Internal system identifier for the wallet.

Error Responses

The API always wraps errors in a standard envelope:

{
  "data": null,
  "errorResponse": {
    "timestamp": "2025-11-18T07:27:18.576590102Z",
    "httpStatus": 200,
    "path": "POST /services/wallet",
    "errorData": [
      {
        "errorCode": "291-406-202-667",
        "message": "Required String parameter 'currency' is not present"
      }
    ]
  }
}

Common Error Conditions

Scenario	Example Error
Missing `partnerId`	`"Missing request header 'partnerId' for method parameter of type String"`
Missing `customerId`	`"Required String parameter 'accountId' is not present"`
Missing `currency`	`"Required String parameter 'currency' is not present"`

Example Request

cURL

curl -X POST 'https://caas-staging.coinme.com/services/wallets?customerId=0837483434346836473&currency=USDC_POL&correlationId=trace_12345' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \

List Wallets for a Customer

GET /services/wallets

Returns all deposit wallets configured for a given customer.

Query Parameters

Name	Type	Required	Description
`customerId`	string	Yes	The customer identifier assigned by your system.

Successful Response (200)

{
  "walletAddresses": [
    {
      "walletAddress": "0x9BBA1ccAfBbE5D729435C748019bB2EF3a7D8cE2",
      "currencyName": "USDC_POL",
      "currencySymbol": "USDC_POL",
      "assetId": "19630",
      "chain": "Polygon"
    }
  ]
}

Field Reference

Field	Description
`walletAddress`	On-chain deposit address for receiving funds.
`currencyName`	Token/Coin name.
`currencySymbol`	Symbol used when retrieving wallets (e.g., `USDC_POL`).
`assetId`	Coinme asset ID.
`chain`	Blockchain network (e.g., Polygon, Ethereum).

Example Request

cURL

curl -X GET 'https://caas-staging.coinme.com/services/wallets?customerId=0837483434346836473' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'partnerId: h3gbsd98jS7sSW938' \