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.

This is the base URL of the CryptoTax KESt Solution API: https://kest-api.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

200

OK

post/api/v1/bzst/capital-gains-exemption-announcement/
https://kest-api.cryptotax.io/api/v1/bzst/capital-gains-exemption-announcement/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

get/api/v1/bzst/capital-gains-exemption-announcement/{capitalGainsExemptionAnnouncementId}
https://kest-api.cryptotax.io/api/v1/bzst/capital-gains-exemption-announcement/{capitalGainsExemptionAnnouncementId}

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

200

OK

post/api/v1/bzst/exceptional-inquiry/{investorIds}
https://kest-api.cryptotax.io/api/v1/bzst/exceptional-inquiry/{investorIds}

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

200

OK

post/api/v1/bzst/regulatory-inquiry/{investorIds}
https://kest-api.cryptotax.io/api/v1/bzst/regulatory-inquiry/{investorIds}

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

200

OK

get/api/v1/bzst/submission/{submissionId}
https://kest-api.cryptotax.io/api/v1/bzst/submission/{submissionId}

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

200

OK

post/api/v1/bzst/submission/{submissionId}
https://kest-api.cryptotax.io/api/v1/bzst/submission/{submissionId}

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

200

OK

get/api/v1/payout
https://kest-api.cryptotax.io/api/v1/payout

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

200

OK

post/api/v1/payout
https://kest-api.cryptotax.io/api/v1/payout

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "custom_payout_identifier": "string",
  • "payout_amount_total": 0,
  • "payout_date": "2020-07-07",
  • "payout_decision_date": "2020-07-07",
  • "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

200

OK

get/api/v1/payout/{payoutId}
https://kest-api.cryptotax.io/api/v1/payout/{payoutId}

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

204

No Content

delete/api/v1/payout/{payoutId}
https://kest-api.cryptotax.io/api/v1/payout/{payoutId}

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

200

OK

get/api/v1/payout/{payoutId}/details
https://kest-api.cryptotax.io/api/v1/payout/{payoutId}/details

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

200

OK

post/api/v1/payout/{payoutId}/realize
https://kest-api.cryptotax.io/api/v1/payout/{payoutId}/realize

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

200

OK

get/api/v1/elster/capital-gains-tax-announcement/{announcementId}
https://kest-api.cryptotax.io/api/v1/elster/capital-gains-tax-announcement/{announcementId}

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

200

OK

get/api/v1/investor
https://kest-api.cryptotax.io/api/v1/investor

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
string

academic title of the investor

address_supplement
string

address supplement

birth_name
string

birth name of the investor

birthplace
string

birthplace of the investor

city
string

city

country
string

country

country_of_birth
string

country of birth of the investor

custom_investor_identifier
string

a custom unique identifier to assign to this investor

date_of_birth
string <date>

investor's date of birth

first_name
string

first name of the investor

german_tax_id
string

German tax id of the investor

house_number
string

house number

house_number_supplement
string

house number supplement

investor_tax_details
object (InvestorTaxDetailsDto)
is_non_resident_tax_payer
boolean

indicates whether the investor is a non-resident of Germany

joint_tax_assessment
boolean

indicates whether the investor and their spouse participate in a joint tax assessment

last_name
string

last name of the investor

name_affix
string

name affix of the investor

spouse
object (InvestorSpouseDetailsDto)
street_address
string

street address

token_holdings
number

token holdings of the investor

zip_code
string

zip code

Responses

200

OK

post/api/v1/investor
https://kest-api.cryptotax.io/api/v1/investor

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "academic_title": "string",
  • "address_supplement": "string",
  • "birth_name": "string",
  • "birthplace": "string",
  • "city": "string",
  • "country": "string",
  • "country_of_birth": "string",
  • "custom_investor_identifier": "string",
  • "date_of_birth": "2020-07-07",
  • "first_name": "string",
  • "german_tax_id": "string",
  • "house_number": "string",
  • "house_number_supplement": "string",
  • "investor_tax_details":
    {
    },
  • "is_non_resident_tax_payer": true,
  • "joint_tax_assessment": true,
  • "last_name": "string",
  • "name_affix": "string",
  • "spouse":
    {
    },
  • "street_address": "string",
  • "token_holdings": 0,
  • "zip_code": "string"
}

Get information about an investor

This API endpoint gives you the information on file about an investor.

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

id of the investor

Responses

200

OK

get/api/v1/investor/{investorId}
https://kest-api.cryptotax.io/api/v1/investor/{investorId}

Update investor information

This API endpoint lets you update the information on file for an investor

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

investorId

Request Body schema: application/json

investor

academic_title
string

academic title of the investor

address_supplement
string

address supplement

birth_name
string

birth name of the investor

birthplace
string

birthplace of the investor

city
string

city

country
string

country

country_of_birth
string

country of birth of the investor

date_of_birth
string <date>

investor's date of birth

first_name
string

first name of the investor

german_tax_id
string

German tax id of the investor

house_number
string

house number

house_number_supplement
string

house number supplement

is_non_resident_tax_payer
boolean

indicates whether the investor is a non-resident of Germany

joint_tax_assessment
boolean

indicates whether the investor and their spouse participate in a joint tax assessment

last_name
string

last name of the investor

name_affix
string

name affix of the investor

spouse
object (InvestorSpouseDetailsDto)