Celsius Partner API

openapi: 3.1.0
info:
  title: Celsius Partner API
  version: 1.0.0
  summary: Partner-facing wallet, interest, KYC and utility API for the Celsius Network platform (retired).
  description: 'The Celsius Partner API (also called the Wallet API) let Celsius Network partners deposit
    and withdraw crypto, earn interest, read balances and transactions, run KYC on their users and read
    utility reference data.


    Three partnership types shared one contract. **Omnibus Integration** and **Omnibus Treasury** partners
    authenticated with `X-Cel-Partner-Token` plus `X-Cel-Api-Key`; **Segmented Integration** partners
    created a Celsius wallet per end user and authenticated with `X-Cel-Partner-Token` plus `X-Cel-User-Token`.
    Every response carried an `X-Signature` header the official SDK verified against a per-environment
    RSA public key.


    **This API is retired.** Celsius Network filed for Chapter 11 on 2022-07-13, emerged on 2024-01-31,
    and shut down its mobile and web apps on 2024-02-29 as part of the wind-down of its business operations.
    The production host `wallet-api.celsius.network` no longer resolves. This document is preserved as
    a historical record of the contract.


    **Provenance.** Derived by API Evangelist from two first-party artifacts, both fetched 2026-08-02:
    the Celsius API public Postman collection (https://documenter.gw.postman.com/api/collections/4207695/Rzn6v2mZ)
    and the official npm package `celsius-sdk@1.0.0` (`lib/consts.js` PATHS and `lib/core.js`). No path,
    verb, parameter, response shape or example in this document was invented.'
  contact:
    name: Celsius Network partnerships
    email: partners@celsius.network
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-apievangelist-status: retired
  x-apievangelist-derived-from:
  - https://documenter.gw.postman.com/api/collections/4207695/Rzn6v2mZ
  - https://www.npmjs.com/package/celsius-sdk
servers:
- url: https://wallet-api.celsius.network
  description: 'Production. Retired: the host no longer resolves as of 2026-08-02.'
- url: https://wallet-api.staging.celsius.network
  description: 'Staging / sandbox. Retired: the host no longer resolves as of 2026-08-02.'
tags:
- name: Wallet
  description: Balances, accrued interest, transactions, deposits and withdrawals.
- name: KYC
  description: Know-Your-Customer application submission and status.
- name: Users
  description: Creation and maintenance of partner-owned Celsius users (Segmented Integration).
- name: Utility
  description: Reference data, statistics, terms of use and health.
security:
- partnerToken: []
  userToken: []
- partnerToken: []
  apiKey: []
paths:
  /kyc:
    get:
      operationId: getKycStatus
      summary: Get KYC status
      description: Returns the user's KYC application status together with an object of rejection reasons.
        `reasons` can be empty when there are no rejection reasons or the user has not been rejected;
        when keys are present the value is always `consider`.
      tags:
      - KYC
      responses:
        '200':
          description: KYC application status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycStatus'
              examples:
                example:
                  value:
                    status: REJECTED
                    reasons:
                      other: consider
                      original_document_present: consider
                      visual_authenticity: consider
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: &id001
                    message: Due to local laws and regulations, Celsius cannot provide its services to
                      individuals from your region. For additional support, contact app@celsius.network.
                    slug: COMPLIANCE_ERROR
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: &id002
                    message: Coin is invalid!
                    slug: COIN_NOT_FOUND
    post:
      operationId: verifyKyc
      summary: Submit KYC data for verification
      description: Creates the KYC application from the supplied form data and identity documents and
        starts the KYC verification process. Segmented Integration partners only.
      tags:
      - KYC
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                first_name: &id003
                  type: string
                  description: Applicant's first name.
                last_name: &id004
                  type: string
                  description: Applicant's last name.
                middle_name: &id005
                  type: string
                  description: Applicant's middle name.
                title: &id006
                  type: string
                  description: Applicant's title, e.g. Mr, Mrs.
                date_of_birth: &id007
                  type: string
                  format: date
                  description: Applicant's date of birth (YYYY-MM-DD).
                citizenship: &id008
                  type: string
                  description: Applicant's country of citizenship.
                country: &id009
                  type: string
                  description: Applicant's country of residence.
                state: &id010
                  type: string
                  description: Applicant's state of residence.
                city: &id011
                  type: string
                  description: Applicant's city of residence.
                zip: &id012
                  type: string
                  description: Applicant's postal code.
                street: &id013
                  type: string
                  description: Applicant's street.
                building_number: &id014
                  type: string
                  description: Applicant's building number.
                flat_number: &id015
                  type: string
                  description: Applicant's flat number.
                ssn: &id016
                  type: string
                  description: Applicant's US Social Security Number.
                itin: &id017
                  type: string
                  description: Applicant's US Individual Taxpayer Identification Number.
                national_id: &id018
                  type: string
                  description: Applicant's national identity number.
                gender: &id019
                  type: string
                  description: Applicant's gender.
                document_type:
                  type: string
                  description: Type of the identity document being uploaded.
                document_front_image:
                  type: string
                  format: binary
                  description: Front image of the identity document.
                document_back_image:
                  type: string
                  format: binary
                  description: Back image of the identity document.
              required:
              - first_name
              - last_name
              - date_of_birth
              - citizenship
              - country
              - city
              - zip
              - street
              - gender
      responses:
        '200':
          description: KYC data submitted and the verification process started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                example:
                  value:
                    message: Kyc started.
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: &id020
                    message: You cannot withdraw less than 1$.
                    slug: DUST_CHECK_FAILED
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /users:
    post:
      operationId: createUser
      summary: Create a partner user
      description: Creates a user in the Celsius system on behalf of a Segmented Integration partner and
        returns the `userId`. The supplied `user_token` is subsequently used as the user secret (`X-Cel-User-Token`).
      tags:
      - Users
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                first_name: *id003
                last_name: *id004
                middle_name: *id005
                title: *id006
                date_of_birth: *id007
                citizenship: *id008
                country: *id009
                state: *id010
                city: *id011
                zip: *id012
                street: *id013
                building_number: *id014
                flat_number: *id015
                ssn: *id016
                itin: *id017
                national_id: *id018
                gender: *id019
                email:
                  type: string
                  format: email
                  description: Applicant's email address.
                user_token:
                  type: string
                  description: Partner-generated token identifying this user.
              required:
              - first_name
              - last_name
              - date_of_birth
              - citizenship
              - country
              - city
              - zip
              - street
              - gender
              - user_token
      security:
      - partnerToken: []
      responses:
        '200':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id020
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
    put:
      operationId: updateUserEmail
      summary: Update the user's email address
      description: Updates the email address of the authenticated user.
      tags:
      - Users
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: New email address for the user.
              required:
              - email
      responses:
        '200':
          description: Email updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFlag'
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id020
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /users/{userId}:
    put:
      operationId: updateUser
      summary: Update a partner user
      description: Updates the profile of an existing user created by the partner.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: Id of the user in the Celsius system.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                first_name: *id003
                last_name: *id004
                middle_name: *id005
                title: *id006
                date_of_birth: *id007
                citizenship: *id008
                country: *id009
                state: *id010
                city: *id011
                zip: *id012
                street: *id013
                building_number: *id014
                flat_number: *id015
                ssn: *id016
                itin: *id017
                national_id: *id018
                gender: *id019
      responses:
        '200':
          description: User updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFlag'
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id020
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /users/{userId}/kyc:
    get:
      operationId: getKycVerificationStatus
      summary: Get KYC verification status for a user
      description: Returns the KYC status for an existing user id. Same shape as getKycStatus but scoped
        to a user the partner already created.
      tags:
      - KYC
      parameters:
      - name: userId
        in: path
        required: true
        description: Id of the user in the Celsius system.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: KYC status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycStatus'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
    post:
      operationId: startKycVerification
      summary: Start KYC verification for an existing user
      description: Starts the KYC verification process for an existing user id. Unlike verifyKyc this
        does not create the user; it uploads identity documents for a user the partner already created.
      tags:
      - KYC
      parameters:
      - name: userId
        in: path
        required: true
        description: Id of the user in the Celsius system.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document_type:
                  type: string
                  description: Type of the identity document being uploaded.
                document_front_image:
                  type: string
                  format: binary
                  description: Front image of the identity document.
                document_back_image:
                  type: string
                  format: binary
                  description: Back image of the identity document.
              required:
              - document_type
      responses:
        '200':
          description: KYC verification started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                example:
                  value:
                    message: Kyc started.
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id020
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/balance:
    get:
      operationId: getBalanceSummary
      summary: Get balance for all coins
      description: Returns the user's balance in each coin supported by Celsius.
      tags:
      - Wallet
      responses:
        '200':
          description: Balances returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSummary'
              examples:
                example:
                  value:
                    balance:
                      eth: '998.000000000000000000'
                      btc: '0'
                      ltc: '0.00500000'
                      cel: '1659.0569'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/{coin}/balance:
    get:
      operationId: getCoinBalance
      summary: Get balance for a coin
      description: Returns the user's balance in a specific coin and its value in USD.
      tags:
      - Wallet
      parameters:
      - &id021
        name: coin
        in: path
        required: true
        description: Coin symbol, e.g. BTC, ETH, USDC. See getSupportedCurrencies.
        schema:
          type: string
          examples:
          - BTC
      responses:
        '200':
          description: Balance for the coin returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoinBalance'
              examples:
                example:
                  value:
                    amount: '0.00525'
                    amount_in_usd: '312.44'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/interest:
    get:
      operationId: getInterestSummary
      summary: Get accrued interest for all coins
      description: Returns the user's accrued interest in each coin and its value in USD, plus the total
        amount accrued in USD across all coins.
      tags:
      - Wallet
      responses:
        '200':
          description: Accrued interest returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterestSummary'
              examples:
                example:
                  value:
                    interest:
                      BTC:
                        amount: 0
                        amount_usd: 206.20390147513007
                        amount_cel: '1659.0569'
                        coin: BTC
                    total_amount_usd: '2909.35'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/transactions:
    get:
      operationId: getTransactionSummary
      summary: Get all transactions
      description: Returns a paginated list of all the user's transactions, sorted by the `time` property
        in descending order.
      tags:
      - Wallet
      parameters:
      - &id022
        name: page
        in: query
        required: false
        description: Page to retrieve. Defaults to the first page.
        schema:
          type: integer
          minimum: 1
          examples:
          - 2
      - &id023
        name: per_page
        in: query
        required: false
        description: How many records are shown per page. Defaults to 20 records.
        schema:
          type: integer
          minimum: 1
          examples:
          - 20
      responses:
        '200':
          description: Transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPage'
              examples:
                example:
                  value:
                    pagination:
                      total: 8
                      pages: 3
                      current: 2
                      per_page: 3
                      showing: 4 - 6
                    record:
                    - id: 74092e77-0a8e-460b-b87a-29b7a401bc1a
                      amount: '1053.888361'
                      amount_precise: '1053.888361068924293393'
                      amount_usd: '27925.078284'
                      coin: ETH
                      state: confirmed
                      nature: interest
                      time: '2020-10-07T13:53:14.000Z'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/{coin}/transactions:
    get:
      operationId: getCoinTransactions
      summary: Get all transactions for a coin
      description: Returns a paginated list of all the user's transactions for the specified coin, sorted
        by the `time` property in descending order.
      tags:
      - Wallet
      parameters:
      - *id021
      - *id022
      - *id023
      responses:
        '200':
          description: Transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPage'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/transactions/{transaction}/status:
    get:
      operationId: getTransactionStatus
      summary: Get transaction status
      description: Returns the state and blockchain hash for the supplied Celsius transaction id.
      tags:
      - Wallet
      parameters:
      - name: transaction
        in: path
        required: true
        description: Transaction id in the Celsius system.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Transaction status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatus'
              examples:
                example:
                  value:
                    tx_id: null
                    state: processing
        '400':
          description: Bad request. Validation failed or the withdrawal amount is below the minimum.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id020
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
  /wallet/{coin}/deposit:
    get:
      operationId: getDeposit
      summary: Get deposit address
      description: Returns the deposit address for the specified coin. When `coin` is BTC the `address`
        is the segwit deposit address and `addressSecondary` carries the legacy address.
      tags:
      - Wallet
      parameters:
      - *id021
      responses:
        '200':
          description: Deposit address returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositAddress'
              examples:
                example:
                  value:
                    address: '0x8fed6d0ad578b7f4beb7aa04de81da9b94244e4f'
        '401':
          description: Unauthorized. Missing or invalid partner/user credentials, or the request is blocked
            by compliance for the user's jurisdiction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id001
        '422':
          description: Unprocessable entity. The request was well formed but could not be fulfilled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: *id002
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example:
                  value: &id024
                    msg: No free addresses available.
  /wallet/{coin}/withdraw:
    post:
      operationId: withdraw
      summary: Withdraw funds
      description: Withdraws the requested amount of the specified coin to the supplied address. The address
        must satisfy the partner's withdrawal scheme (no address / list of pre-approved addresses / any
        address).
      tags:
      - Wallet
      parameters:
      - *id021
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: Address to which to withdraw the funds.
                amount:
                  type: string
                  description: Amount to withdraw, as a numeric string.
              required:
              - address
              - amount
      responses:
        '200':
          description: Withdrawal accepted.
          content:
            application/json:
              schema:
  

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/openapi/celsius-network-partner-api-openapi.yml