CryptoTax KESt Solution API (1.0)

Download OpenAPI specification:Download

Introduction

The CryptoTax KESt Solution API gives the token issuer the ability to manage all token investors and related information (KISTAM, etc.). The API also helps the token issuer calculating all tax-relevant data as a result of a payout event. Moreover, the CryptoTax KESt Solution API integrates with the ELSTER API of the German Tax Authority, thereby allowing the token issuer to directly submit a capital gains tax application to the German Tax Authority.

These are the base URLs of the CryptoTax KESt Solution API:

Production environment: https://kest-api.cryptotax.io/

Test environment: https://kest-api-test.cryptotax.io/

Authentication

The CryptoTax KESt Solution API is secured using JWT tokens. You must pass your individual token for each request using the HTTP header parameter Authorization.

Example:
Authorization: Bearer <token>

BZSt

Bzst Api

Announce capital gains exemptions for a tax year (§ 45d EStG) for an investor

This API endpoint triggers an announcement about all capital gains exemptions for the specified tax year and investor to the BZSt according to § 45d EStG. This announcement is due once a year and must not happen any later than end of February for the previous tax year.

Authorizations:
key (global)
Request Body schema: application/json

exemptionAnnouncementDto

investor_id
integer <int64>

id of the investor

tax_year
integer <int32>

the tax year

Responses

Request samples

Content type
application/json
{
  • "investor_id": 0,
  • "tax_year": 0
}

Get capital gains exemptions announcement (§ 45d EStG)

This API endpoint fetches information about a capital gains exemption announcement.

Authorizations:
key (global)
path Parameters
capitalGainsExemptionAnnouncementId
required
integer <int64>

id of the capital gains exemption announcement

Responses

Exceptional inquiry to the BZSt

This API endpoint triggers an exceptional inquiry to the BZSt for the specified investors.

Authorizations:
key (global)
path Parameters
investorIds
required
string

a comma-separated list of investor ids

Responses

Regulatory inquiry to the BZSt

This API endpoint triggers a regulatory inquiry to the BZSt for the specified investors. It is compulsory to make regulatory inquiries for all investors once a year. Moreover, the regulatory inquiries must be made between September 1 and October 31.

Authorizations:
key (global)
path Parameters
investorIds
required
string

a comma-separated list of investor ids

Responses

Query status information about a BZSt submission

This API endpoint retrieves status information about a BZSt submission as specified by the submission id.

Authorizations:
key (global)
path Parameters
submissionId
required
integer <int64>

id of the BZSt submission

Responses

Check and collect answer data for a BZSt submission

This API endpoint checks and collects any new answer data from the BZSt for a previously submitted BZSt inquiry.

Authorizations:
key (global)
path Parameters
submissionId
required
integer <int64>

id of the BZSt submission

Responses

Tax id inquiry to the BZSt

This API endpoint triggers a tax id inquiry to the BZSt for the specified investors.

Authorizations:
key (global)
path Parameters
investorIds
required
string

a comma-separated list of investor ids

Responses

Capital Gains Payout

Capital Gains Payout Api

Get a list of all capital gains payouts

This API endpoint gives you list of all capital gains payouts for the specified year

Authorizations:
key (global)
query Parameters
year
required
integer <int32>

year

Responses

Prepare a new capital gains payout event

This API endpoint lets you create and prepare a new capital gains payout event.

Authorizations:
key (global)
Request Body schema: application/json

payout

custom_payout_identifier
string
payout_amount_total
number
payout_date
string <date>
payout_decision_date
string <date>
payout_timeframe
string

Responses

Request samples

Content type
application/json
{
  • "custom_payout_identifier": "string",
  • "payout_amount_total": 0,
  • "payout_date": "2019-08-24",
  • "payout_decision_date": "2019-08-24",
  • "payout_timeframe": "string"
}

Prepare a new custom capital gains payout event

This API endpoint lets you create and prepare a new custom capital gains payout event.

Authorizations:
key (global)
Request Body schema: application/json

payout

custom_payout_identifier
string
Array of objects (CustomInvestorCapitalGainsPayoutDto)
payout_amount_total
number
payout_date
string <date>
payout_decision_date
string <date>
payout_timeframe
string

Responses

Request samples

Content type
application/json
{
  • "custom_payout_identifier": "string",
  • "investors_data": [
    ],
  • "payout_amount_total": 0,
  • "payout_date": "2019-08-24",
  • "payout_decision_date": "2019-08-24",
  • "payout_timeframe": "string"
}

Get a capital gains payout by id

This API endpoint retrieves a capital gains payout by id

Authorizations:
key (global)
path Parameters
payoutId
required
integer <int64>

id of the payout to retrieve

Responses

Delete a capital gains payout event

This API endpoint lets you delete a capital gains payout event. Please note, that a deletion is only possible if a payout has not been realized yet, i.e. no data was submitted to the German Tax Authority via ELSTER.

Authorizations:
key (global)
path Parameters
payoutId
required
integer <int64>

payoutId

Responses

Get all details for a capital gains payout by id

This API endpoint retrieves a capital gains payout by id. It also provides detailed information on the individual payouts to the investors.

Authorizations:
key (global)
path Parameters
payoutId
required
integer <int64>

id of the payout to retrieve

Responses

Realize a capital gains payout event

This API endpoint realizes an already prepared capital gains payout event. By realizing the capital gains payout event, it will also announce it to ELSTER. In the response you will get a elster_submission_id for the realized capital gains payout event which can be used to query on the status of the announcement to ELSTER.

Authorizations:
key (global)
path Parameters
payoutId
required
integer <int64>

id of the payout to realize

Responses

ELSTER

Elster Status Api

Query the status of an ELSTER capital gains tax announcement

This API endpoint allows querying on the status of a ELSTER capital gains tax announcement.

Authorizations:
key (global)
path Parameters
announcementId
required
integer <int64>

id of the ELSTER capital gains tax announcement

Responses

Investor

Investor Api

Get a list of all investors

This API endpoint gives you list of all active investors for the specified issuer token.

Authorizations:
key (global)

Responses

Create a new investor

This API endpoint creates a new investor to your token

Authorizations:
key (global)
Request Body schema: application/json

investor

academic_title