Celsius Network

Celsius Network KYC API

Know-Your-Customer application submission and status.

GitHub OpenAPI

Documentation

📖
APIReference
https://documenter.getpostman.com/view/4207695/Rzn6v2mZ

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/openapi/celsius-network-kyc-api-openapi.yml

Other Resources

🔗
Postman
https://www.postman.com/labs-celsiusnet-decents/celsius-public/documentation/tsw6j4r/celsius-api
🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/postman/celsius-network-partner-api.postman_collection.json
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/data-model/celsius-network-data-model.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/errors/celsius-network-problem-types.yml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/celsius-network/refs/heads/main/apis.yml

OpenAPI Specification

celsius-network-kyc-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Celsius Partner KYC 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.'
security:
- partnerToken: []
  userToken: []
- partnerToken: []
  apiKey: []
tags:
- name: KYC
  description: Know-Your-Customer application submission and status.
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:
                    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:
                    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:
                  type: string
                  description: Applicant's first name.
                last_name:
                  type: string
                  description: Applicant's last name.
                middle_name:
                  type: string
                  description: Applicant's middle name.
                title:
                  type: string
                  description: Applicant's title, e.g. Mr, Mrs.
                date_of_birth:
                  type: string
                  format: date
                  description: Applicant's date of birth (YYYY-MM-DD).
                citizenship:
                  type: string
                  description: Applicant's country of citizenship.
                country:
                  type: string
                  description: Applicant's country of residence.
                state:
                  type: string
                  description: Applicant's state of residence.
                city:
                  type: string
                  description: Applicant's city of residence.
                zip:
                  type: string
                  description: Applicant's postal code.
                street:
                  type: string
                  description: Applicant's street.
                building_number:
                  type: string
                  description: Applicant's building number.
                flat_number:
                  type: string
                  description: Applicant's flat number.
                ssn:
                  type: string
                  description: Applicant's US Social Security Number.
                itin:
                  type: string
                  description: Applicant's US Individual Taxpayer Identification Number.
                national_id:
                  type: string
                  description: Applicant's national identity number.
                gender:
                  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:
                    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:
                    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:
                    message: Coin is invalid!
                    slug: COIN_NOT_FOUND
  /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:
                    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:
                    message: Coin is invalid!
                    slug: COIN_NOT_FOUND
    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:
                    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:
                    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:
                    message: Coin is invalid!
                    slug: COIN_NOT_FOUND
components:
  schemas:
    Message:
      type: object
      description: Simple message envelope.
      properties:
        message:
          type: string
        msg:
          type: string
    Error:
      type: object
      description: Celsius error envelope. `slug` is the stable machine-readable error code and `message` the human-readable text; older responses use `msg` instead of `message`.
      properties:
        message:
          type: string
          description: Human readable error message.
        msg:
          type: string
          description: Legacy human readable error message.
        slug:
          type: string
          description: Stable machine-readable error code.
          examples:
          - COMPLIANCE_ERROR
          - COIN_NOT_FOUND
          - INSUFFICIENT_FUNDS
    KycStatus:
      type: object
      description: State of a KYC application.
      properties:
        status:
          type: string
          description: Status of the KYC application.
          enum:
          - COLLECTING
          - PENDING
          - PASSED
          - REJECTED
          - PERMANENTLY_REJECTED
        reasons:
          type: object
          description: Rejection reasons keyed by reason name; each value is always `consider`.
          additionalProperties:
            type: string
  securitySchemes:
    partnerToken:
      type: apiKey
      in: header
      name: X-Cel-Partner-Token
      description: Partner key issued by Celsius and securely provided to the partner. Required on every authenticated request, for every partnership type.
    userToken:
      type: apiKey
      in: header
      name: X-Cel-User-Token
      description: User token created by the partner for each of its users. Used by Segmented Integration partners.
    apiKey:
      type: apiKey
      in: header
      name: X-Cel-Api-Key
      description: API key issued by Celsius and securely provided to the partner. Used by Omnibus and Omnibus Treasury partners.