API Version: 2.18.0

[Enhancement] Updates to crypto transfers endpoints

We introduced important updates to our Crypto Transfers API endpoints, which include aligning element names and introducing new ones related to fiat currency support. These enhancements are designed for partners utilising our crypto transfers endpoints for deposits and withdrawals. The updates ensure consistency and expand support for fiat currency in transaction reporting.

[New Feature] Validate crypto address for withdrawals

This new endpoint allows partners to validate a Crypto address before initiating a withdrawal, ensuring that the address is correct and compatible with the selected asset and network. If the address is invalid or incompatible, the API will return a detailed error message before proceeding with the withdrawal.

[Enhancement] Addition of min_withdrawal_fee and min_whtdrawal_threshold elements to the asset network information data

The minimal amount of the crypto withdrawal and the minimal fee, which will be charged for the crypto withdrawal. These parameters can be used to do a pre-validation on the entered withdrawal amount and to display the minimal fee to be charged before the user proceeds with the withdrawal. Keep in mind that the actual fee applied may be higher and will be calculated and returned in the following withdrawal steps. The minimum fee can be used as a comparison of the withdrawal costs of different networks.

Updates on:

• GET Asset List
• GET Asset List V2
• GET Asset Details
• GET Asset Details V2

For any questions or further assistance, please reach out to our support team.

API Version: 2.17.0

Webhooks Version: 1.6.0

[New Feature] Automated Buy Orders

New feature added to simplify and automate investing: Automated Buy Orders. This enhancement allows your users to specify a price target at which a buy order will be executed. Once the market price reaches the set target price, a market buy order will be automatically placed. The target price can be above the current price to initiate a stop buy order or below the current price to initiate a limit-market order.

Key benefits:

• Automated trading: simplify the trading process by automating the execution of buy orders based on predefined price targets.
• Strategic flexibility: enable your users to implement advanced trading strategies, such as buying at specific market conditions, thereby maximising potential gains.
• Improved UX: enhance the user experience by providing more control and responsiveness to market movements.

You have the ability to offer to users all the related tasks needed to manage these orders: create, cancel, view. Once an order is automatically executed or cancelled due to specific reasons, we will notify you using the already existing mechanisms: Webhooks & GET Events. This allows you to further notify your users, keeping them informed and engaged.

Getting started:

• To explore the new Automated Orders feature, please refer to this section in the API docs for detailed instructions and examples.
• To start integrating it into your applications, please reach out to our support team to guide you through the process and the required configurations.

Coming soon: Automated Sell Orders are expected in the future iterations. This feature will allow your users to set the target price below the current price to initiate a stop loss order or above the current price to initiate a take-profit order. Keep you posted.

[Enhancement] Addition of name element to the asset network information data

The name of the asset network, used for displaying and identifying the network during crypto transfers (deposits or withdrawals). This parameter can be used for clearer and more accurate display of the network which will be used during the crypto transfer.

Updates on:

• GET Asset List
• GET Asset Details

[Enhancement] Introduce v2 of asset list and asset details endpoints

This update is the initial phase of migrating the asset endpoints from using numeric IDs to UUIDs, enhancing the security of asset identification. Future phases will continue this migration for additional asset endpoints.

Changes:

• The path parameter id of the GET Asset Details endpoint now uses UUID instead of a numeric ID.
• The response parameter id in both endpoints returns a UUID

New Endpoints:

• GET Asset List
• GET Asset Details

Thanks for being our partner!

Your BTS team

API Version: 2.16.1

Webhooks Version: 1.5.1

[Enhancement] Addition of type_defined_for element for Non-user Initiated Transactions

We enhanced the Non-user initiated transactions and the related notifications by adding a new element, type_defined_for. This element is available to easily identify if a transaction type refers to asset or fiat amounts. It is particularly useful for transactions where both amounts are provided, including the equivalent in fiat of the asset amounts (e.g. asset giveaways).

Possible Values:

• asset: Indicates that the transaction type refers to asset amounts.
• fiat: Indicates that the transaction type refers to fiat amounts.
• Note: Both values cannot be set simultaneously.

Updates on:

• GET Non-user Initiated Transactions V2
• GET Notification Events (type user.non-user-initiated-tx-v2)
• Webhook Notifications Non-user Initiated Transactions V2

Thank you for using our solution!

API Version: 2.16.0

[New Feature] Transaction Timeline per User Endpoint

We recently introduced the Transaction timeline per user endpoint, a powerful new feature designed to enhance data retrieval for our partners.

Key Highlights:

• Comprehensive Data Extraction: Partners can now extract transactions per user for all categories or select specific ones, providing greater flexibility and customization to meet various needs.
• Single Endpoint Integration: Simplify your integration process by using a single endpoint to access all transaction data, reducing development time and complexity.
• Timeline-Based Approach: Retrieve data based on a timeline, ensuring that the most recent transactions are returned first, optimized for front-end display.
• Pagination Support: Specify a size for transactions to be displayed, along with a cursor for seamless navigation through large datasets.

We believe that this feature will significantly improve how you access and display transaction data per user, providing you with greater control and efficiency.

Over time, we plan to phase out the existing category-specific endpoints that currently provide redundant information (e.g. List all trades per user).

API Version: 2.15.0

Webhooks Version: 1.5.0

[New Feature] Crypto Actions Notifications

We just added support for crypto actions to our notifications service. Crypto actions refer to events or changes that affect crypto assets, similar to traditional corporate actions in the stock market. The new notifications will provide our partners with real-time updates that may impact the value, structure, or functionality of their users’ crypto assets.

This feature was implemented to support the recent AGIX, OCEAN & FET migration to ASI. We introduced a specific event type called "merger_crypto" where two or more crypto assets are combined into a single, unified asset. This process is comparable to corporate mergers.

How to enable crypto actions

The notifications are now available using both webhooks and GET events with user.crypto-action endpoint. Feel free to start integrating them into your solution.

Reach out to our team to configure the webhook endpoint where you wish to receive the new events.

[Product Update] API Support for Businesses

Our solution now supports the management of businesses via API to enable trading at the business level. This new addition, available under User Administration, allows you to handle business details, authorized individuals, shareholders, directors, and various roles to streamline your corporate operations.

How to get started

• API documentation: Check out our API documentation section here for detailed instructions.
• Integration support: Contact our support team to help you with API integration and configuration.

For any questions, just give us a shout - our support team is standing by, ready to help!

API Version: 2.14.1

Webhooks Version: 1.4.0

[Announcement] New notification examples for corporate actions & non-user initiated transactions notifications via Webhooks

We are pleased to announce the addition of new examples in our documentation. These examples cover notifications for corporate actions and non-user initiated transactions via Webhooks, providing you with clear guidance on how to implement this feature effectively.

[Product Update] Enhanced decimal precision for GET Prices endpoint

We introduced an important improvement to our Get prices endpoint, designed to enhance the accuracy and reliability of price data across all assets, especially those with smaller prices.

What's Changed:

• Previous behaviour: The GET Prices endpoint previously returned prices with only 2 decimal places. While this was sufficient for assets with larger prices, it was not ideal for assets with smaller prices, leading to potential inaccuracies in price representation.
• New behaviour: To address this issue, we have updated the GET Prices endpoint to return prices with 8 decimal places. This change ensures that all assets, regardless of their price range, are displayed with high precision, providing you with more accurate and detailed pricing information. We do not expect any impact on your side, but if you have any questions, please reach out to our support team for assistance.

API Version: 2.14.0

Webhooks Version: 1.4.0

[Action Required] Enhanced Notifications Service

We are happy to announce we improved our Notification Service! This updated version includes enhancements aimed at providing a more robust and reliable communication channel with our partners.

Here's what's new

• Retry Mechanism
  • We can now handle retries for sending notifications, which will significantly reduce the likelihood of missing any.
  • We define a call as successful if the webhook responds with one of the following status code family: 2xx.
  • If the endpoint returns a different status code, the webhook will attempt retries as follows:
    • Three retries at one-minute intervals.
    • If these attempts fail, the system will retry every 15 minutes, up to a maximum of 50 retries.
• Performance Improved
  • The updated version ensures faster processing times and reduced latency.
• Enhanced Webhook Events
  • The fields in the webhook events will always be included in every payload to ensure consistency per notification type.
  • Some fields may contain null values depending on data availability. Please ensure your application logic can handle null values where data may not always be available.

Who is impacted?

• API Endpoint Integrators: Partners who integrate via Get Events will see the following response changes:
  • meta.page_size renamed into meta.size
  • meta.total_count removed
• Webhooks Integrators: Partners who integrate via webhooks will see the following changes per notification type:
  • User Update
    • Removed: domain_id, domain_slug
    • Modified: optional fields now become present and nullable if there is no value.
  • Top-Up Request
    • Removed: domain_id, domain_slug
    • Modified: optional fields now become present and nullable if there is no value.
  • Top-Up Success
    • Removed: domain_id, domain_slug
    • Modified: optional fields now become present and nullable if there is no value.
  • Send Money
    • Removed: domain_id, domain_slug
    • Modified: optional fields now become present and nullable if there is no value.
  • Send Money Success
    • Removed: domain_id, domain_slug
    • Modified: optional fields now become present and nullable if there is no value.
  • Non-User-Initiated Transaction
    • Added: related_offer_id (set to null)
    • Modified: Timestamp format changed from +00:00 to Z
    • Modified: optional fields now become present and nullable if there is no value.
  • Non-User-Initiated Transaction V2 (newly added)
    • Added: related_offer_id (set to null), fiat_id, fiat_amount
    • Modified: Timestamp format changed from +00:00 to Z
    • Modified: optional fields now become present and nullable if there is no value.
  • Corporate Actions
    • Removed: domain_id, domain_slug
    • Modified: timestamp format changed from +00:00 to Z
    • Modified: optional fields now become present and nullable if there is no value.

How to switch to the latest version

• Partners will need a configuration change on our side to move to the latest version. In the staging environment, we have already configured all partners to use and test the enhanced version.

• If there are any concerns with the mentioned changes please let us know within the next week. If we do not receive your confirmation by this date, we will assume there is no impact and will automatically migrate you to the improved version starting on June 21st, 2024.

If you have any questions, please reach out to our support team for assistance.

API Version: 2.13.0

Webhooks Version: 1.3.0

[Announcement] API Documentation now publicly available

As part of our commitment to improving the developer experience and fostering a more open environment, our API documentation is now available publicly. Developers can now access documentation instantly, speeding up the development and integration process. We encourage you to visit the updated API documentation site and familiarise yourself with the enhanced content and structure.

[Product Feature] WebSocket for asset prices and price changes

We are excited to announce the launch of a new feature on our platform: WebSocket support for asset prices and price updates. Our new WebSocket channels are designed to offer efficiency and to provide asset data that is crucial for trading and analysis.

Why Use WebSocket for Asset Prices?

WebSocket technology enables a faster, more efficient way to receive asset price data without the need to continuously poll or fetch updates. This means you get up to date prices directly through a continuous stream.

Key Features and Benefits:

1. Real-Time Updates: Subscribe to 'prices-v1' and 'price-changes-v1' channels to receive updates every 15 seconds.
2. Efficient Resource Management: Avoid the overhead of frequent API calls. WebSocket connections reduce the need to poll for data, decreasing your system's workload and improving response times.
3. Ease of Use: Setting up a WebSocket connection is straightforward—just follow the same authentication process you’re accustomed to and connect using the designated endpoint. Once connected, you can subscribe to different channels as per your needs.
4. Customizable Data Streams: receive only relevant data by choosing the specific asset-fiat pairs that are needed
5. Maintained Connection Integrity: Our WebSocket servers support ping/pong messages to keep the connection alive, ensuring continuous data delivery without interruptions.

For detailed instructions on how to set up and use your WebSocket connection, please refer to the Price WebSockets section in the API Documentation

[Product Update] Get trade tax details endpoint

To help users get a better understanding of taxes applied to each trade and the capital gains realised, we have introduced a new endpoint:

• GET /v1/tax-withholding/{Offer-id}

Based on the trade UUID, users can get their capital gains and taxable amount for any completed trade:

• The capital gain or capital loss represents the profit/loss on the individual sell trade before loss netting. It's calculated based on sales proceeds - acquisition costs (e.g. you acquire an asset for 100 EUR & sell it for 200 EUR, capital gain = 200 - 100 = 100).
• The taxable amount is the amount after loss netting, which is used as the basis of the tax calculation. It may be the same as the capital gain, however, it may also be less than the capital gain as a result of loss netting.

[Action Required] Get non-user initiated transactions with split fiat & asset amounts

To enhance functionality and clarity, we have divided the amount field into two distinct fields, fiat_amount and asset_amount, while getting transactions related to non-user-initiated activities. This enhancement V2 allows for transactions where asset giveaways are specified either in a fiat amount or as an asset amount. In case of asset amount, the fiat amount will be calculated at execution time based on asset amount and current market price. The fiat_amount is now denominated in euros. To accommodate transactions in multiple currencies, we also introduced the fiat_id field.

Please note that all new fields plus related_offer_id can be nullable, depending on the specifics of the related activities.

Make sure you start consuming the improved one, as version 1 will be deprecated in 6 months. [31 October 2024]

SWAPS

Introduction:

This is a friendly reminder about our Swaps feature, which enables users to exchange one asset for another, without needing a traditional exchange or fiat currency, within our platform. This feature enables seamless, direct transactions between different assets, making it user friendly, reducing friction and increasing transaction volumes.

Keys statistics and benefits recap:

• 34% of the trade volume is generated through Swaps
• Average number of transactions per user on Swaps is 20% higher than normal trades
• Having a Swaps feature increases the number of transactions as users are more likely to swap than to sell as it convenient and easy
• 25% of active traders comes from Swap users
• The decision-making process of trading involves a careful reflection on the financial aspect - "I need to use X amount to buy Y amount which then exposes me to Z risk". However swaps decrease the barrier to that decision

For more information on how to leverage Swaps within our platform, please refer to the updated API documentation or reach out to our support team for assistance.

New URLs for asset logos and updated format

As previously communicated on March 6th, there will be changes to the URLs and format of asset logos. These changes aim to enhance the accessibility and presentation of asset logos within our platform.

Key Details:

• Effective Date:
  • Staging Environment: April 4th
  • Production Environment: April 22nd

Changes:

• The new logo format will be PNG, transparent, with a default size of 512x512
• The new logo URL will be accessible as a value of the response parameter "logo" in the endpoints GET /v1/assets and GET /v1/assets/{id}
• Sample logo: https://cdn.cms.staging.waskurzes.com/logos/v4/asset/light/ea895436-edee-11eb-9bf0-06502b1fe55d.png

Partner specific information for a user

• Endpoints:

  • POST /v2/users
  • PATCH /v2/users/{User-ID}

• Description: Two optional request parameters have been added to the above endpoints to accommodate partner-specific information.

  • external_id (Optional, unique)

    • Description: This parameter represents a unique external identifier of the user on the Partner side. It serves as a means of linking user data between our platform and our partners'.
    • Note: The identifier shall be unique. If the identifier is already assigned to another user from your domain, the create/update user request will fail
    • Type: string, max length 255 characters
    • Example usage: "external_id": "cd9715ee-cefa-11ee-a3e8-07f1c1852501"

  • external_meta (Optional)

    • Description: This parameter allows for the inclusion of additional user information necessary for partner-specific data processing or required due to compliance reasons.

    • Type: object, contains a list of key-value pairs

    • Example usage:

      "external_meta":
      {
          "branch": "1240",
          "account_type": "primary"
      }
      

Get a list with terms and conditions, which an existing user shall accept

• Endpoint:
  • GET /v1/users/{User-ID}
• Description: A new response parameter has been introduced to retrieve a list of terms and conditions that an existing user must accept. This functionality allows for seamless management of user agreements, ensuring compliance and user consent.
• Parameter:
  • terms_not_accepted
    • Description: List of mandatory terms that have not been accepted by the user
    • Type: array of integers
    • Items of the array
      • Type: integer
      • Description: Term ID representing the specific terms that the user has not accepted yet.

Multi currency support in endpoints, providing asset prices

• Endpoints
  • GET /v1/assets
  • GET /v1/assets/{id}
  • GET /v1/asset-groups/{group}/assets/{id}
• Description: This update introduces multi-currency support for endpoints providing asset prices. By including a currency parameter in the request, users can retrieve asset prices in the corresponding fiat currency.
  • currency (Optional)
    • Type: string, ISO4217 currency three letter code
    • Description: Specifies the desired fiat currency for asset prices.
    • Example usage: ?currency=USD
    • Supported currencies: EUR, USD, CHF, GBP, TRY, PLN, HUF, CZK, SEK, DKK
  • If the query parameter is omitted, prices are returned in EUR by default

Fixed inconsistencies

• Endpoint GET /v1/users (Search for users)

  • The response parameter "trading_active" has been removed from the documentation to accurately reflect the actual response of the endpoint.

• Endpoints GET /v1/assets and GET /v1/assets/{id}

  • The response parameter "network_information" and its nested objects within “network” are now marked as nullable to align with the endpoint's behaviour.

Off-boarding user endpoint enhancements

• Endpoint: POST /v1/users/{User-ID}/off-boarding

• Description: This endpoint now supports two additional optional request parameters to provide more flexibility and customization during the off-boarding process.

  country_of_residence (Optional):

  • Description: Represents the current country of residence of the user being off-boarded.
  • Format: ISO 3166-1 alpha-2 format (e.g., "ES" for Spain, "DE" for Germany).
  • Example Usage: country_of_residence=ES

  liquidate_assets (Optional):

  • Description: Provides a recommendation on whether to liquidate the assets as part of the off-boarding process.
  • Note: The final decision regarding asset liquidation remains with the platform.
  • Values:
    • true: Requests liquidating assets.
    • false: Requests not liquidating assets.
  • Example Usage: liquidate_assets=true

Important Note

• It's important to emphasise that the off-boarding of users and the potential liquidation of assets are not executed automatically. Each case is subject to manual review by our team to ensure compliance and adherence to our policies and procedures.

Asset ID filter in trade history endpoint

• Endpoint: GET /v1/trades

• Description: This endpoint now supports one additional optional request parameters to provide more flexibility for trades filtering

  asset_id (Optional):

  • Description: Represents the asset id that can be filtered in the trade history endpoint. When provided only the trades for that specific asset will be displayed
  • Example Usage: asset_id=1

Non-user initiated transactions changes

• With the current mechanism, partners receive an incoming giveaway "non-user initiated transaction" notification with the new crypto amount during coin migrations. However, what was missing to complete a crypto swap was a new outgoing (or incoming negative amount) giveaway to erase the former crypto.
• Now, you will also be informed by the giveaway (asset deduction) through either calling the non-user-initiated-transactions endpoint or processing a non-user-initiated-transactions webhook notification. This ensures a more comprehensive and accurate notification system during coin migrations, facilitating smoother crypto swaps.
  • Endpoint GET /v1/non-user-initiated-transactions
  • Description: The current functionality remains unchanged; however, the endpoint will now incorporate a new transaction type called 'deduction'.

Crypto transfers

We're thrilled to introduce an enhanced Crypto Transfers feature supporting both deposits and withdrawals. This functionality provides a seamless experience for moving digital assets between our platform and external brokers/wallets. Follow the steps outlined below to utilise this powerful capability.

Note: Crypto Transfers are currently available for a select subset of crypto assets. To enable this feature, please reach out to our account team, as it is not activated for all accounts. We're here to tailor your experience to suit your specific needs.

How to use crypto transfers?

Getting coin and network information

To obtain a list of coins, for which transfer is available and details about the networks to be used, we have added the parameter network_information to the following endpoints: GET /v1/assets and GET /v1/assets/{id}

• The parameter will be returned only if transfers are supported for the given coin
• network_information provides a list of supported networks and the default network, recommended for transfers of this crypto asset.
• In the network details, among others, you can find the status of the network (is deposit/withdrawal active, is the network operational), as well as information about the minimum transfer amount, network logo, etc.

Deposits

1. Create a deposit address

   Endpoint: POST /v1/crypto-transfers/addresses

   • This endpoint allows users to create a new blockchain address on a specified network. If an address on that network already exists for the user, the existing address will be returned. You need to pass the network_id, retrieved in the previous step. The response contains all the necessary information in order to initiate a deposit

2. Initiate the deposit

   • the obtained wallet address details can be used by the customer to initiate a deposit from their external broker.

3. Deposit status notifications

The status of your deposits may change during processing. You will receive notifications on each change in deposit status, keeping you informed of the progress.

• Webhook Notifications: Ensure you have set up webhook endpoints to seamlessly receive these updates
• Alternative Notification Method: If you prefer, you can also check for deposit status changes by searching for new events through the GET /v1/events endpoint.

Withdrawals

1. Create a withdrawal offer

   Endpoint: POST /v1/crypto-transfers/withdrawals/offer

   • Create a withdrawal offer that requires confirmation for execution.
   • Select a network and add the destination address (and, if necessary, the destination tag type and destination tag).

2. Confirm withdrawal:

   Endpoint: POST /v1/crypto-transfers/withdrawals/confirm/{withdrawal-id}

   • Execute the withdrawal by confirming the offer.
   • It is recommended to request additional user authentication (e.g. MFA) before calling the confirm endpoint.

3. Check withdrawal status

   Similar to the deposits, you will be notified about the withdrawal status via webhook or by searching for new crypto withdrawal events

Transaction Details

1. Get Details for a Single Transaction

   Endpoint: GET /v1/crypto-transfers/transactions/{transaction-ID}

   • Retrieve detailed information for a specific transaction by calling this endpoint.
   • Obtain insights into transaction status, type, and more.

2. Get a List of Transactions for a User

   Endpoint: GET /v1/crypto-transfers/transactions

   • Access a list of transactions for a particular user.
   • Utilize additional criteria such as transaction status, type, and more for effective search capabilities.

List of Addresses

Get a List of Crypto Addresses

Endpoint: GET /v1/crypto-transfers/addresses

• Retrieve a comprehensive list of crypto addresses associated with a given user.
• Further filter the results using supported query parameters for targeted information.

Tax withholding refund settlement

For partners that are using the settlement endpoint POST /v1/fiat-stock we also added the option to report for refunds as part of the settlement process. This means that this endpoint now accepts a 3rd type as a direction (refund).

Similar to what we do when trading, it is recommended to call update fiat stock endpoint for every processed refund to inform us that the user received the funds.

When this type is used the reference provided should match the id of the refund (found in the Non User Initiated transactions endpoint). The amount should also match and when this endpoint is called Bitpanda will have the confirmation that the refund amount was sent back to the user.

Assets API updates

In order to uniquely identify ETFs and ETCs, the ISIN (identification number) has been added to the responses of GET ETF and GET ETC details. This can now be displayed to users in the frontend.

Tax withholding improvements

Warning message with code tax.withholding.not.available has been added in the create offer response. It is returned in the case when tax calculation uses the pessimistic approach.

Based on this code, a message can be added to explain to the user that the transaction will incur 27.5% tax withholding amount, which will then be partially or fully refunded.

related_offer_id associated with the offer_id is added to the non user initiated transactions API response. Partners can now match the tax refund and the offer ID.

related_offer_id is only populated for tax_refund transaction type. Every tax refund will have an associated offer id.

Overview

Austria has implemented a new cryptocurrency tax framework that mandates a 27.5% flat tax rate, applicable to crypto assets purchased from March 1, 2021, onwards. Starting from January 1, 2024, Austrian cryptocurrency service providers are required to implement a withholding tax system for all crypto transactions conducted by Austrian residents.

Bitpanda adhering to these regulations, must withhold 27.5% of Austrian resident’s personal income tax and forward it to the Austrian tax authorities.

Entities covered: Bitpanda GmbH for:

• Bitpanda GmbH users who have an Austrian address (in scope or eligible status)
• Bitpanda GmbH users who have a non-Austrian address and are
  • Austrian citizens or
  • Citizens of neighbouring countries: citizens of adjacent nations (Germany, Switzerland, Liechtenstein, Czech Republic, Slovakia, Hungary, Slovenia and Italy) must self-declare that they do not possess a residence (not even a secondary home) or habitual abode in Austria (EStR Rz 7745) to avoid being taxed. Otherwise they will also be subject to the applicable taxation

Note: Other Austrian Bitpanda entities (e.g. Bitpanda Financial Services GmbH, Bitpanda Payments GmbH, Bitpanda Metals GmbH) are not in scope by the new rules.

Tax Information on Trade Endpoints

The below endpoints, now available in PROD, have been edited to provide tax information:

1. Create Offer (for clarity we will take a 100 EUR sell example where the tax is 10 EUR)
   • fiat_amount:
     • Existing functionality and users that are not eligible for taxes: 100 EUR
     • For users that are eligible for taxes: 90 EUR
   • total_amount (new field):
     • For non-eligible users total_amount will be the same as fiat_amount: 100 EUR
     • For eligible users: 100 EUR (it will be fiat_amount + tax_amount)
   • tax_amount (new field):
     • For non-eligible users tax_amount will be 0
     • For eligible users: 10 EUR (going with the same example as above)
2. Accept Offer
   • Same fields as above
3. Trade Search
   • Same fields as above
4. Trade History (same fields as above)

User Tax Information

Two new endpoints have been added to retrieve and modify (where needed) the tax status of the users.

1. GET /v1/tax-status
   • This information will return the eligibility status of the user, with the available responses:
     • Eligible: user is in scope for tax withholding
     • Not eligible: user is not in scope and will not pay taxes
     • Unknown: user will require self-certification (a call to the next endpoint), confirming whether the user answers ‘yes’ or ‘no’ to the question of confirming if the user regularly lives in Austria or has a home in Austria (the self-certification question needs to be applied to Austrian citizens and citizens of neighbouring countries residing outside of Austria)
2. PUT /v1/tax-status/{user_id}
   • Payload should be {"is_eligible":true|false}
   • For a user with status Unknown this endpoint will make the user eligible or non-eligible

Important Notes on User Tax

• Users that have ‘unknown’ status will be taxed if they don’t complete the self certification
• Until the self-certification flow can be implemented by the partner, we will provide a list of users with ‘unknown’ status on a weekly basis. With your feedback (sent by email) with confirmation of ‘true’ or ‘false’ for tax eligibility, we will then set the correct status (‘eligible’ or ‘not eligible’) in the system

For more information and example, please see our knowledge base article: Austria Tax Withholding and Austria Tax FAQ & User Experience

Get Prices Endpoint

We currently provide a base price for the asset a user is interested in. However, when a user proceeds to purchase the asset, the displayed price changes to include the fee.

To improve the experience, we’ve introduced an endpoint (GET v1/prices?asset_id=1&fiat_id=1&type=buy) to present users with a more precise asset price inline with the accepted offer price. This endpoint ensures that the initial price quoted, seen before creating an offer, includes all relevant fees (both account level and asset-specific), offering a more accurate reflection of the final buy price.

Notes:

• This endpoint is particularly relevant in scenarios where users view the preliminary price before creating an offer. If the offer is created directly or the preliminary price isn't displayed, then this feature may not be applicable
• The endpoint will require the user_id in the header (like all the other ones) and based on the asset fee and the account level of the user will return a unit price that takes all the fees into consideration
• The steps for Create an Offer (POST /v1/offers) and Accept an Offer (PATCH /v1/offers/{Offer-ID}/accept), are still needed
• This new endpoint comes into play when a user selects a particular asset and specifies the amount, just before the step of creating an offer

Sample response:

 "data": {
    "id": 1,
    "symbol": "BTC",
    "price": "37749.85"
 }

User API Updates

1. verification.language: when creating or updating a user, sending a language parameter in the verification object is now optional
2. ext_compliance: when using the create and update user v2 endpoints, a new optional parameter is added to send compliance related data, such as user PEP status, risk level or last date when Partner conducted a KYC check on the user.

Assets API updates

1. We are improving the user experience by introducing further asset filtering capabilities (previously you could only filter by ‘type’ or ‘group’) Two request query parameters are introduced in GET /v1/assets (types[] and groups[]) when searching by multiple asset groups of asset types, which allows to move from only being able to query by one type and/or group, to being able to filter the list of assets by multiple types and groups

   For example, if you want to get a list with all Bitpanda Stocks, ETFs and metals, you can use the following query: groups[]=stock&groups[]=etf&groups[]=metal

2. Q is introduced to get information on a specific asset Search by asset symbol or asset name: by using request query parameter q you can search by either part or the full asset name or by the symbol.

   For example, q=btc

Portfolio API Updates

401 "Invalid user" error added to the error response list of portfolio overview, groups, performance, and assets endpoints

New version of accept offer endpoint

We have introduced an idempotent version of our AcceptOffer endpoint to enhance its behaviour. In essence, each call to this new endpoint with the same payload will consistently yield an identical response, regardless of the number of calls made.

Examples:

• If the initial response was 202, you call the endpoint again and the offer is still in progress, you will again get a 202 response code.
• If the endpoint returned a successful response and you call it again with the same payload, then you will get the exact same trade details, as you received during the first call.
• It is possible that you receive 202 initially and when you call the endpoint for a second time, you get a response with the trade’s final status. In the v1 version of the endpoint, for all scenarios described above, any subsequent calls made after the initial one will result in an error message.

New approach:

Endpoint	Step	Possible responses	Response details
PATCH /v2/offers/{Offer-ID}/accept	Initial call	200 or 202	Either the offer body or empty body in case of 202
PATCH /v2/offers/{Offer-ID}/accept	Any subsequent calls	200 or 202	Either the offer body or empty body in case of 202 (offer is still pending)

Additional trading error code

A new error is added to the 422 errors list of PATCH /v1/offers/{Offer-ID}/accept endpoint .

{
  “code”: “trading.limit.reached”,
  “title”: “Settlement account balance reached trading stop limit.”
}

The error will be returned when the unsettled trading amount in the Partner’s settlement account reaches a predefined trading stop limit. Example: even after reaching the lower settlement threshold of e.g. 300K, we do not receive deposits from the Partner. Buy trades are still performed, thus the settlement balance is reduced even further. When the Partner’s settlement wallet amount reaches a trading stop limit of e.g. 0 EUR, we will return the above error on the next buy trade. When a settlement deposit is received or sell trades are performed (which will increase the value of the corporate settlement wallet), buy trades will be conducted again.

Portfolio performance per asset groups

We have added a new endpoint, which returns the current portfolio fiat amount and the return percentage, split per asset group: GET v1/portfolio/groups/overview/fiats/{fiatId} .
It can be used for creating a portfolio view, showing the current user’s portfolio distribution per asset group. Hence, If a user owns both TSLA and GOOG stocks along with BTC, two different return percentages will be returned since these assets belong to different groups (coin and stock).

Portfolio performance for 6m and more than a year

Additionally to the daily, weekly, monthly and yearly portfolio performance, you can now get the overall portfolio performance for the previous 6 months (period = 6m) or from the beginning of the user’s activity (period = max).

Assets historical price changes

In addition to the existing supported price change periods (day, week, month, year, 5 years), you can now retrieve the historical price changes for an asset over the last 6 months. This new feature expands our time frame options, offering you even more detailed time-sensitive information.

Documentation fixes

Some response parameters in all GET asset-group endpoints are marked correctly as nullable (GET /v1/asset-groups/*). This means that some response parameters are not mandatory. They can either be present with a value or completely absent, represented as null.

Assets categorisation

Assets categorisation allows users to have advanced categories / asset clusters to discover assets in specific sectors / themes selectable based on the users’ interests.

We have introduced a set of categories that ease customers into the topic of trading. Customers can discover assets based on specific themes they may understand, e.g. “Energy”, “Technology”, “Automotive”, “Defi”, etc. Asset sub-categories (also referred to as groups or tags) are part of an asset category. Example of a category is “Region” with sub-categories (groups/tags) Europe, North America, Asia, Latin America, Africa, Oceania and Global. Each asset can be tagged with multiple tags, e.g. Tesla falls into two groups - “North America” and “Automotive”.

How to get the up-to-date categories and sub-categories?

Call the following endpoint:

• GET /v1/tags

You will receive the full list of categories and their sub-categories (groups). Check our API documentation for request/response details.

How do I get the list of sub-categories (tags) per asset?

A new response parameter asset_tags is added to the get asset list and get single asset details endpoints.

• GET /v1/assets
• GET /v1/assets/{asset_id}

It contains a list of sub-categories, by which the asset is tagged. Note that this list is not final and may change in time.

Can I filter assets by a sub-category?

When calling GET /v1/tags endpoint you will receive a parameter “label” for each sub-category (all sub-categories begin with asset_tag.group prefix). Use these values as search parameters when calling GET /v1/assets endpoint.

Example:

https://test.whitelabel.bitpanda.com/v1/assets?tags[]=asset_tag.group.automotive&tags[]=asset_tag.group.north_america

The result will contain a list with all assets, which are tagged as belonging to “Automotive” AND “North America”. You can continue using the other available filters of the GET /v1/assets endpoint also in combination with asset tags filtering.

Non-user initiated transactions

Endpoints are available in production. For more information check the release notes from 7th June.

User email can be updated

A new request parameter email is added to the PATCH /users/{User-ID} endpoint. If a user changes their email address, you can provide this information in the PATCH user endpoint.

5 years asset price change added

The 5 years price change of an asset is added to endpoints:

• GET Assets /v1/assets
• GET Asset Details /v1/assets/{asset_id}

Additionally to the daily, weekly, monthly and yearly change, the 5 years price change is available via two new response parameters change_5y and change_5y_amount.

Small documentation fixes:

• Asset type etc (Exchange Traded Commodity) is appended to the asset group enum values of GET Assets and GET Asset Details endpoints
• Error codes cleanup: proof_of_funds error removed from create and accept offer response list
• market_cap is correctly set as nullable in the responses of all GET asset details endpoints (GET /v1/asset-groups/*)
• The two possible responses of GET Enhanced portfolio details of an asset are now merged into one. This was done in order to support automated client generation in more programming languages.

Staking

• Search: parameter start_date is renamed to date_start and parameter end_date is renamed to date_end, for consistency with the rest of the search endpoints. Also, the codes of the corresponding validation errors have been updated to contain the new parameter names.
• Stake/Unstake: success response 202 is added. Similar to trading 202 response, it will mean that the stake/unstake action has been accepted, but not yet processed. It will be returned if the stake/unstake action has not been processed within 5 seconds.
• Get staking transaction status: A new endpoint to fetch the current stake/unstake transaction status is introduced. You can call it in case you get a 202 response for stake/unstake action. Recommendation: call it once per second until you get the transaction final status (success or failed)

Get user details

Two additional response parameters are added to GET user details endpoint, showing whether the user must retake the appropriateness test or if the test, completed by the user, is the most up - to - date one.

• "requires_test_completion": true | false,
• "requires_test_resubmission": true | false

File upload

The following restrictions are introduced to endpoint POST /v1/files:

• Image MIME types: when uploading an image, only the MIME types listed below will be accepted:
  • image/bmp
  • image/x-ms-bmp
  • image/x-bmp
  • image/jpeg
  • image/png
  • image/heic
  • image/heif
• There are no additional restrictions for the accepted MIME types for the rest of the files (video, pdf, etc.)
• File name (applicable for all files)
  • Shall be between 3 and 255 characters long
  • Shall not begin with a dot (.)
• File size shall be between 15B and 50MB (applicable for all files)

Nullable response parameters

This is only a documentation fix. Some response parameters, which can be nullable, were not shown as such in the documentation:

• GET /v1/assets/{id} and GET /v1/assets
  • market_cap
  • staking

Pagination

In all endpoints, the type of request parameters page and page_size and response parameters page, page_size and total_count was updated to integer to reflect the actual values those parameters can have. Up till now the type was defined as number in the documentation.

Non-user initiated transactions

What is a non-user initiated transaction?

By non-user initiated transactions we mean transactions, which are not triggered by the user. Some examples of such transactions are:

• metal storage fees, which are deducted once per week from the user metal asset amount
• giveaways , e.g. if a user received asset as a result of a marketing campaign or as a result of an airdrop
• staking rewards, which are granted once per week to users, having staked assets

To get a list with these transactions, use the following endpoint: GET /v1/non-user-initiated-transactions

Alternatively (or additionally) you can subscribe to receive webhook notifications for non-user initiated transactions.

There will not be a dedicated staking reward webhook any more. Staking rewards will be sent in the non-user initiated transactions webhook notifications.

The endpoint will be available on Staging from 14.06.2023 onwards.

Staking information

• assets endpoint response Response parameters in the staking section of the GET /v1/assets and GET /v1/assets/{id} response are updated to use pothole (snake) case. Also, a new parameter next_reward_at is added to this section. It shows when the next staking reward for this asset will be given to the users, which are eligible to receive a reward.
• next_reward_at in the stake response It returns the date, when the user will receive the first reward for the currently staked asset amount. Note that the next_reward_at parameter in the asset endpoint response and the stake response may be different. The reason for that is that an asset amount shall be staked for at least 48 hours before it becomes eligible for a reward. The 48 hour period could be changed in future.

Appropriateness test

It is no longer mandatory to provide the appropriateness answers during user onboarding. Appropriateness test shall be conducted latest before the first trade with stocks or ETFs. If the answers are not available at that time, the trade with stock/etf will be declined and an error will be returned: appropriateness.questionnaire.is.not.submitted

Bug fixed - verification language not supported

If the language in the verification object is not among the ones, supported by Bitpanda, you will receive an error message user.verification.language. The verification language shall be one of the Bitpanda supported languages.

Duplicate users check

When registering a new user or updating an existing one, a validation is performed checking if a user with the same first name, last name and birthdate is already registered for the same domain. If such a user is found, an error during the registration/update will be returned user.first_name.last_name.birthdate.already_exists.

Will be enabled in PROD on 14.06.2023.

Trading v2 endpoints

We have removed the v2 trading endpoints from the staging section of the documentation. The transition to our new trade engine is done in a transparent manner, by gradually redirecting trading requests to it. The gradual rollout is done for almost all Partners already. There is no need to implement calls to v2 trading endpoints.

Blacklist user endpoint has been deprecated

As already announced in January

Events or Webhooks - it is your choice!

You are not using webhook notifications or you want to make sure that you have not missed one? Check the new GET /v1/events endpoint. By calling it you can get all new notifications, generated after a past event (which you can define when calling the service). The list with possible notifications (also available as webhooks) can be found here.

payment_reference added to the settlement transactions search response

To help you uniquely match settlement transactions when working on reconciliation, payment_reference is added to the below two endpoints:

• GET /v1/trades/transactions

Increased granularity of the endpoint response GET /v1/portfolio/performance/fiats/{fiatId}/timeframe/{period}

• day: from 24 data points (1 per hour) to 144 (1 per 10 min)
• week: from 56 (8 per day) to 168 (1 per hour)
• month: from 30 (1 per day) to 120 (4 per day)
• year: from 52 (1 per week) to 180 ( 1 each two days)

New error code (409 offer.not.latest) when accepting an offer

/v1/offers/{Offer-ID}/accept will return 409 in the body instead of 503 (service unavailable) if the user has created two offers that are still valid and is accepting the first one.

• "code": "offer.not.latest",
• "title": "A newer offer was created"

This improvement covers the scenario where:

• User creates offer A
• User creates offer B (after a couple of seconds)
• Both offers are still valid
• User accepts offer A. As per the rules of our trade engine, the user can only accept offer B . At the moment we are returning Service unavailable error with 503 HTTP status code in the described scenario. What we will return is 409 HTTP status code that will contain the errorcode offer.not.latest and errortitle = A newer offer was created.

Change is applicable only to Partners, using our new trade engine

Heads up: Savings plans are coming soon

Savings Plan allows customers to setup an automated investment in a few steps:

1. Choose the asset
2. Define the frequency (weekly, bi-weekly or monthly)
3. Make sure there's enough money in the account
4. Ready - Sit back and relax while the investment grows over time!

Setting up recurring trades is a very simple process and can bring important benefits to your customers:

• Automated investment removes the stress of 'timing the market'. Instead, customers invest when they have the money
• little by little.
• By investing frequently, users can benefit from the cost average effect - Constantly acquiring an asset is a good strategy to 'smooth out' market volatility and reduces the dependency on short term price fluctuations:
• The term “cost average effect” describes the mathematical phenomenon that happens when customers make a set of small, equal investments in assets which have fluctuating prices.
• The more volatile an asset is, the stronger the cost average effect. This applies regardless if the price is trending upwards or downwards.
• Users can set up as many savings plans as they want and for any digital asset supported on Bitpanda.

How to create and execute a Savings Plan?

• Create a recurring Savings plan by calling POST /v1/savings-plan
• Subscribe for webhook “Savings Plan Notification” or get the user.savings-plan-notification event to know which savings plan occurrence is upcoming.
• Based on the above notifications, reserve the corresponding fiat amount from the user’s account
• After the amount is booked, confirm the execution of the savings plan occurrence, by calling PATCH /v1/savings-plan/transaction/{external-transaction-id}/confirm
• After the Savings plan trade is done, you will get a notification in both success and failure cases. Either subscribe to webhooks Savings Plan Trade Success Notification, Savings Plan Trade Error Notification and/or get the corresponding events user.savings-plan-trade-notification(success), user.savings-plan-trade-notification(failure)
• After successful savings plan execution, the fiat amount will be reflected in your corporate wallet balance

You can also:

• Cancel a Savings Plan: PATCH /v1/savings-plan/{id}
• Search for Savings Plans: GET /v1/savings-plan

OAuth2.0

Added support for authentication based on the OAuth2.0 standard. We suggest to have a look in the Authentication section and also check out the new OAuth2.0 APIs here and here.

Search for trades endpoint response changes

GET /trades/search endpoint gives you the option to search for trades, which are not only user initiated. It also allows you to see the trades for both active and deactivated users.

• parameter initiated_by is added to the response.

It provides information whether the trade was initiated by a user or by some Bitpanda action. If, for example, the trade was caused by a corporate action, e.g. stock delisting, then the initiator will be bitpanda_corporate_action. If the trade resulted from a user off-boarding and assets liquidation, then the initiator will be bitpanda_manual_trade, etc.

Possible values: user, bitpanda_corporate_action, bitpanda_manual_trade, bitpanda_savings, other.

• new query parameter user_pid allows you to search trades for a particular user (can be used for both active and deactivated users)

• if the trade is not user initiated and doesn't have a corresponding external (Partner) id, then response parameter external_transaction_id will be null.

New status code added

The response 202 Accepted is added to the PATCH /v1/offers/{Offer-ID}/accept response list, to reflect better the behaviour of the endpoint after the gradual rollout to trading v2 begins. If the trade was redirected to trading v2 and the offer is not processed within 5 seconds, then 202 Accepted will be returned.

To check the offer status, use GET /v1/offer-status/{Offer-ID} endpoint.

Update missing response text for 503 status code

"code": "service.unavailable" was missing as a possible response example in the 503 error list.

Future changes announcement

Heads up: The following changes will be available as of 08.02.2023 on Staging and 14.02.2023 in Production.

As of now, the response of "Search for trades" endpoint /trades/search contains only user initiated trades. It will be enhanced to return also trades, which were done as a result of corporate actions, off-boarding, savings plans, etc., similar to what the response of "Get trades history for user" endpoint contains /v1/trades.

You will be able to search for all trades, per user or time period. The result will contain trades of both active and deactivated users.

The following changes will be introduced:

• parameter initiated_by will be added to the response.

  It will give information whether the trade was initiated by user or by Bitpanda action. A trade may be result of corporate action, e.g. stock delisting, then the initiator will be bitpanda_corporate_action. If the trade resulted from a user off-boarding, then the initiator will be bitpanda_manual_trade, etc.

  Possible values: user, bitpanda_corporate_action, bitpanda_manual_trade, bitpanda_savings, other

• you will be able to search trades per user, via a new query parameter user_pid

• if the trade is not user initiated and doesnt have a corresponding external (Partner) id, then response parameter external_transaction_id will be null.

Staking is now available via our White Label solution.

Staking allows customers to earn additional rewards just by holding certain cryptocurrencies from Proof of Stake blockchains. Customers can choose from 15 different coins and tokens that generate rewards up to 18.4% per year and benefit from our unique selling points: weekly rewards, no lock-in periods and automatic staked rewards.

The feature is an important differentiator in the market and can drive customer engagement.

The following Staking APIs are introduced:

• get basic staking configuration
• perform a stake and unstake action
• search for staking transactions history

Staking information will be included in the portfolio asset details response, if user has staked portion of his/her owned assets (GET /v1/portfolio/assets/{assetId}/fiats/{fiatId})

Information whether an asset could be staked or not, plus asset staking details, is added to the assets list and asset details responses: GET /v1/assets , GET /v1/assets/{id} . This parameter is present only if staking is available to the users of the Partner, sending the request

If you are using BankID as your customers' verification provider:

• Upload file endpoint (POST /v1/files) allows uploading verification reports in json format
• Passing user’s personal document expiration date in parameter verification.expiration_date becomes optional when creating and updating user data

Deprecations

Blacklist user endpoint (POST /v1/users/{User-ID}/blacklist) will be deprecated as of 23.02.2023

Introducing a new optional response parameter initiated_by to the "Get trades history for user" endpoint GET /v1/trades

Response parameter: initiatedby Type: enum Possible values: user, bitpandacorporateaction, bitpandamanual_trade, other

With the introduction of new features, additional values could be added to this enum.

What is it for? Gives information whether the trade was initiated by the user or was a result of a Bitpanda action. A trade may be caused by a corporate action (e.g. stock delisting), in this case the initiator will be bitpandacorporateaction . If the trade resulted from a user off-boarding, then the initiator will be bitpanda_manual_trade. In exceptional cases the initiator may be other.

A new endpoint to check the status of a trade

You can check the offer status by calling the GET offer status endpoint: GET /v1/offer-status/{Offer_ID}.

Check for the following responses:

• finished - if the offer has been processed and a trade finalised, you will receive status finished in the response.
• 404 offer not_found - if the offer is still being processed or has failed

You can call the endpoint e.g. each second, for the next 20 seconds, until you get status finished. If you don’t get status finished, consider the offer as failed.

With the introduction of trading V2, the GET offer status will return a more comprehensive status list, showing whether the offer is "created" "finished" "in progress" "expired" or "failed".

However, while the trade is executed in the "old" trade engine, the behaviour will be as explained in the previous section.

RPS rate limitation

If the requests per second are above a certain threshold (100 on staging, 200 on production), you will receive an error "Too many requests" with status code 429.

Updated URL to the assets logo

As previously shared, the asset logo URL, returned by GET /v1/assets and GET /v1/assets/{id} endpoints will change for all existing and new assets and will contain asset_id instead of asset symbol.

Transaction Reports

Transaction Reports are now available in production, for more information on transactional reports see this article from our knowledge base.

Historical Asset Price

We have now increased from 1 to 5 years in historical asset price, which can be retrieved via GET asset history endpoint, in addition to the daily, weekly, monthly and yearly historical view.

Portfolio

New Parameters added to the Portfolio asset details endpoint:

• daily_return_percent: the difference in percentage for the last 24h return (yesterday’s return compared to today’s return)

• total_return_percent: represents the all time fiat return, in percentage. This performance is calculated from the point of time when the user first bought the asset

• current_asset_price: the current fiat price of one asset

For reference, all release notes can be found in the API documentation portal and in the WhiteLabel Knowledge Base

Near Future Changes Coming Up

Rate Limitation

Effective in STAGING (Dec 7th) and in PRODUCTION (Dec 12th) environment will be introduced. The total amount of requests on STAGE will be 100 rps, on PROD 200 rps. If you exceed your quota, you will receive error message "Too many requests" with status code 429.

Name Change of Asset Logos

Effective in STAGING (Dec 7th) and in PRODUCTION (Dec 14th) in the GET /v1/assets and GET /v1/assets/{id} endpoints. Currently, the asset name contains the asset symbol, and this symbol may not be unique. We are improving this by renaming the asset logos to contain a unique identifier. This means that the value of the return parameter logo will change for all existing and new assets.

Bear in mind, that for the same asset, the unique identifier will be different on stage and in production.

Trade search and accept offer endpoints

• trade_id is added to the PATCH /v1/offers/{Offer-ID}/accept response. For the time being trade_id and id (which holds the offer_id) will have the same values. When the trading is redirected to the new trading engine, the values will be different.
• offer_id is added to the GET /v1/trades and GET /v1/trades/search responses. For the time being offer_id and id (which holds the trade_id) will have the same values. When the trading is redirected to the new trading engine, the values will be different.

Webhooks and corporate actions

Webhook notifications for corporate actions contain the following two additional parameters:

• id - unique id, identifying a transaction, created as a result of a corporate action
• ca_id - unique id of the particular corporate action. One corporate action contains multiple corporate action transactions

New Endpoint added

Endpoint /v1/asset-groups/token/assets/{id} is added to the Assets section of the documentation. If you need to get asset details for a token, call the above mentioned endpoint.

Endpoint Deprecation

Have in mind that the user registration, update and upload verification files endpoints will be deprecated and will not be supported as of 08.05.2023. Use the corresponding /v2 versions instead:

• POST /v1/users → POST /v2/users
• PATCH /v1/users/{User-ID} → PATCH /v2/users/{User-ID}
• POST /v1/users/{User-ID}/verification → POST /v2/users/{User-ID}/verification

The only difference between the v1 and the v2 endpoints is the way the verification files are delivered from the Partner to Bitpanda. In v2, you shall first upload the file by using the POST /v1/files, store the id, which is returned by the endpoint and pass the id instead of a link to the verification file in the above three endpoints.

Soon to be available in production

You will have the possibility to provide transaction reports, on demand, in case that a user requests one. The report will contain information about all trades and corporate actions, done or applied to a user in a particular time frame. Thus, we have introduced two new endpoints, which will be used to trigger the generation of a transaction report and to fetch it when produced. You can check them out in the Staging section of the API documentation.

Corporate actions notifications

We have improved the corporate actions notification, to contain more comprehensive information about the different types of corporate actions, which are performed on the user’s owned assets (e.g. dividend payouts, delisting, mergers, etc.)

This includes:

• new corporate actions webhook notifications structure (Corporate Actions Notifications)
• new response of /v1/trades/corporate-actions/search
• search by user is supported in endpoint /v1/trades/corporate-actions/search, thus /v1/trades/corporate-actions will be deprecated

Heads up

we are developing a new Authentication mechanism and you will start seeing APIs, related to it, into the "In development" section of the documentation. More information will be provided soon.

New asset group: Exchange Traded Commodities (ETC)

We are launching a new asset class: commodities. They are structured as Exchange Traded Commodities (ETCs). API changes:

• GET /v1/assets - etc is added as a new value to the group query parameter enum
• For detailed information per ETC asset, the endpoint GET /v1/asset-group/ was updated to support ETCs. You can call it in this way: GET /v1/asset-groups/etc/assets/{id}
• The response parameters, returned for ETCs are the same as the ones for ETFs, on all asset endpoints

Reports: Download XPCT Reports

This endpoint returns the ex-post cost transparency report to all users who traded stocks or ETFs in 2021.

• This is due to a legal requirement and must be sent to users on an annual basis
• The report will be created by Bitpanda and must be communicated to users via e-mail
• The language will be defined based on user settings and will be available in English, German, French, Italian, Spanish and Portuguese. When language is not defined on the user settings, English will be used as fallback
• The document is returned in PDF format

Off-boarding

You can use this endpoint to initiate off-boarding in case of an account closure.

File management & User onboarding v2

We are introducing a new method for Partners to provide user verification files. Instead of Bitpanda retrieving the files from Partner’s side, Partners will have the ability to upload files on Bitpanda side, using the same token as for accessing the other endpoints. This will make the whole file sharing process easier for the Partner.

Improvement: New document types for verification object

What?

From now on, you can pass two additional types of documents – paper ID and residence permit – for verifying your customer while creating or updating the user.

How?

We added new possible values for document_type in the verification object for both Create new user and Update an existing user endpoints:

• residence_permit
• paper_id

Improvement: Separated types of staging endpoints

What?

We added other types of endpoints to our staging section. You can currently find:

• v1 endpoints: these endpoints are currently available only in the staging and are not yet released to production – they do not have counterparts at the production instance.

• v2 endpoints: these endpoints are related to a new trade engine, which is still under development.

• in development: these endpoints are not functional yet and serve as a type of ‘roadmap’ of future endpoints planned to release on staging.

How?

To check all staging endpoints, go to the Staging subtab in API reference docs.

Improvement: New optional parameter added to Get Terms & Conditions endpoint

What?

From now on, you can configure different terms and conditions (T&Cs) to accept depending on the user’s country of residence as well as define the default terms and conditions.

If you do not pass the parameter, or the T&Cs are not defined for the given country, the endpoint returns the default T&Cs.

How?

We added a new optional parameter country to the Get Terms & Conditions endpoint.

Improvement: Automated asset listing

What?

From now on, new assets available in Bitpanda app are automatically enabled to all Partner domains. More info about automated asset listing can be found here.

How?

The endpoint Get a list of available assets will return the updated asset list when a new asset is added.

Improvement: Introduced staging endpoints

What?

We introduced new endpoints that are available only in the staging environment. Some of our Partners use these endpoints, but to not confuse the others, we collated them under one drop-down to differentiate them from standard Production endpoints.

How?

To check our staging endpoints, go to the Staging only subtab in API reference docs.

Improvement: Status Page for White Label APIs

What?

Now you can quickly check if all APIs used by Partners are operational on our Bitpanda Status Page.

How?

Scroll down Bitpanda Status Page and find White Label APIs. You can subscribe exclusively for White Label APIs – just tick in desired option while enrolling.

New settlement-related endpoint added

What?

We added a new endpoint POST/fiat-stock used in a particular version of the settlement agreement when the Bitpanda settlement account is opened at Partner’s bank. For the rest of our Partners, this endpoint is irrelevant.

How?

This endpoint is available only for some Partners, depending on the agreed settlement mechanism and used after each trade for updating corporate accounts for both Bitpanda and the Partner.

Introducing Investing Academy – educational content on all things investing

What?

Now you can find a starter pack of educational content which can be used to educate yourself and your teams, but also as material to guide your end users.

Note: The materials are available for all Bitpanda White Label Partners, so you may want to modify them for your own purpose. The texts are on a diverse set of investing topics, from ‘What are altcoins?’ to ‘What is investing and who can invest?’ and designed to be beginner friendly.

How?

We added a new category Investing Academy to the navigation bar, where the articles are sorted according to the categories:

• Assets,
• Blockchain,
• Personal Finance, and
• Risks in Investing.

Update: Verification details added to GET /v1/users/{User-ID} response

What?

From now on, we provide more detailed information about the verification status and the reason for failed verification via a new parameter.

How?

We added a new parameter verification_details to GET /v1/users/{User-ID} response.

    "verification_details": {
  "status": "...",
  "reason": "..."
  }

The status can have one of the following values:

• completed
• failed
• processing

The reason contains helpful details when the status is failed. Here are the exemplary reasons:

• Unable to download the remote file
• Content type is invalid

Update: The birth_place became an optional parameter

What?

Parameter birth_place is no longer obligatory while creating or updating the user. We introduced that change because the birthplace is not available for some document types.

How?

We changed the parameter birth_place to be optional for POST /users and PATCH /users requests.

Improvement: New optional parameter for verification object

What?

Now you can pass the info about the document type used for your customer verification as a separate parameter. It can be useful when your customer did not provide MRZ (Machine-Readable Zone) code.

Note: If you provided both MRZ code and document_type, and the parameter value differs from the MRZ code, the MRZ code will overwrite the document type received in the request.

How?

We added a new optional parameter document_type for verification object to the POST /users and PATCH /users{User-ID} endpoint with the following values:

• pass
• id_card
• driving_license
• other

Improvement: New parameter for SEPA transfer

What?

You can append the type of the SEPA transfer to the deposit information sent to Bitpanda.

How?

We added the optional parameter sepa_type to the POST /deposit endpoint with the following values: instant and classic.

Improvement: User’s trading status

What?

You can check the trading status of a user.

Why?

Trading status may differ from the overall account status – an active user (with account status = active) may have trading deactivated.

How?

GET /users/{User-ID} endpoint contains a new parameter trading_active in its response. If the trading is not active ("status": false), you will also receive a reason for deactivation.

Improvement: Search by phone number

What?

We enabled the possibility to search users by phone number.

How?

GET /users endpoint has the new option for searching users by phone number and not only by email.

Improvement: Translations for AML/appropriateness

What?

We enabled translations to 6 different languages for AML/appropriateness questions and answers. Supported additional languages are German, Polish, French, Spain, Italy and Turkish.

How?

We added to the endpoints GET /aml and GET /appropriateness the new optional parameter Accept-Language. You can pass in its value a string containing ISO 639-1 language code to get the list of AML/appropriateness questions and answers translated into the chosen language. The default language is English (en).