EN flag

Creating a webhook query

Learn how to create Psyll webhook queries for trading automation. This chapter explains the structure of queries, types of actions, and provides examples of their practical use.

Partner image

Webhook

Automate trades and trigger actions by connecting external alerts through fully customizable webhooks.

Webhooks are an extremely flexible and powerful tool for automating trading on the Psyll platform, enabling fast and precise order placement on the exchange using standard HTTP POST requests. This method allows for integration with external systems, such as TradingView, and the creation of fully automated trading strategies.

In this chapter, we will delve into how to construct requests, the types of actions available, and also provide practical examples of usage, potential limitations, and error scenarios.

Structure of a webhook request

Each request to a Psyll webhook must be formatted as a JSON object and contain three fundamental fields:

  • action - The type of operation the system should perform. Possible values are: BUY, SELL, SET.
  • quantity - The number of asset units to be bought, sold, or set. Fractional values are supported, allowing for very precise position control.
  • symbol - The trading pair symbol, consistent with the exchange's convention (e.g., BTCUSDC, ETHBTC).

Example request:

"action": "BUY",
"quantity": 0.0021,
"symbol": "BTCUSDC"

This request instructs the Psyll platform to place a buy order for 0.0021 BTC on the BTC/USDC pair.

The BUY action

After receiving a query with the action set to BUY, the system immediately places a buy order for the specified trading pair on the exchange linked to the user's account. The order will be executed provided there is sufficient capital available in the account. In the case of insufficient funds, the exchange may reject the order or execute it partially. Webhooks place market orders, which are executed at the current best price available on the exchange.

We recommend monitoring the order status in the webhook's return response, which contains details about the order (e.g., order ID, status, quantity of units executed).

Example scenario:

We want to buy 0.5 ETH on the ETHUSDT pair.

"action": "BUY"
"quantity": 0.5"
"symbol": "ETHUSDT"

As a result of executing this webhook, a buy order for 0.5 ETH will be placed. If the user's account has enough USDT, the order will be executed immediately.

The SELL action

The operation is analogous to BUY, but it applies to selling assets. The system places a sell order for exactly the number of units specified in the quantity field.

Example scenario:

We want to sell 0.25 BTC on the BTCUSDT pair.

"action": "SELL"
"quantity": 0.25
"symbol": "BTCUSDT"

In response, the system will confirm that the sell order has been placed. Upon its execution, the equivalent of 0.25 BTC in USDT currency will appear in your account.

The SET action

The SET action is the most advanced and allows for precise control of position size. The system first checks the current balance of a given asset and then calculates the difference between it and the value defined in quantity. Depending on the result, it automatically places a buy or sell order.

  • If the current balance is greater than the quantity, the system automatically places a sell order for the surplus.
  • If the current balance is less than the quantity, the system automatically places a buy order for the missing amount to balance the position.
  • If the balances are equal to the quantity: No action is taken.

This functionality allows you to automatically maintain a position at a predetermined level without the need for manual monitoring or placing separate orders.

Example 1: Selling

If the amount of an asset in your portfolio is less than what you want to sell, the exchange will reject the order.

Your current account balance is 0.023 BTC. We want to maintain a position of 0.01 BTC.

"action": "SET"
"quantity": 0.01
"symbol": "BTCUSDT

The system will automatically calculate that 0.023 - 0.01 = 0.013 BTC needs to be sold. A sell order for 0.013 BTC will be placed, and after it is executed, the account will have exactly 0.01 BTC remaining.

Example 2: Buying

Your current account balance is 0.005 BTC. We want to increase the position to 0.01 BTC.

"action": "SET"
"quantity": 0.01
"symbol": "BTCUSDT"

The system will calculate that the portfolio is short 0.005 BTC (0.01 - 0.005 = 0.005 BTC). A buy order for 0.005 BTC will be placed to bring the balance up to 0.01 BTC.

Futures Exchanges
In the case of futures markets, the interpretation of BUY and SELL actions can differ from spot markets. For example, a SELL order can open a short position, while a BUY order can reduce or completely close an existing short position, depending on the current account status and contract settings.
DUST
When you want to sell leftover assets, also known as "dust," the system often rejects the order because the minimum order value hasn't been met. In most cases, this isn't a problem and can be ignored.

Potential errors

  • Insufficient funds or balance: When attempting to buy without enough base currency (e.g., USDT) or sell without enough quoted currency (e.g., BTC), the webhook will return an error indicating insufficient funds.
  • Asset unavailability: Some exchanges may not support the selected symbol pairs. In such a case, the webhook will return an invalid symbol error.
  • Daily limit: Depending on the subscription plan, your account may have a limit on the number of daily orders. Once this is exceeded, the webhook will not process further requests and will return a daily_limit_exceeded error.
  • Communication errors: In the event of network issues or exchange API errors, the webhook may return a temporary error. It is recommended to implement a retry mechanism in the system sending the requests to try again after a short time.

Practical tips

Webhooks are very flexible, but due to the dynamic nature of the market and different exchange conditions, it's always good to:

  • Monitor order statuses: Regularly check webhook responses and order statuses on the exchange platform.
  • Test requests: Always test your requests in a test environment or with minimal amounts to avoid unwanted operations.
  • Use logical conditions: Use complex conditions on the TradingView side or another signal system to avoid excessive request generation during volatile conditions.
  • Verify the pair symbol: Make sure the pair symbol is correct and supported by the exchange you are connected to.
  • Secure data storage: The webhook address and any API keys should be stored securely.

TradingView Integration

TradingView Alert Integration

The Psyll platform allows for easy integration with TradingView alerts. Simply configure an alert on the TradingView platform and include the appropriate JSON object, which corresponds to the webhook structure, in its message.

This process enables the entire strategy to operate fully automatically, without the need for manual intervention, even in the most volatile market conditions.

More information on the format and interpretation of responses returned by the webhook can be found in our "TradingView alert integration" documentation.

TradingView Strategy Integration (Pine Script)

Psyll supports direct integration with your own strategies created in the Pine Script language in TradingView. This makes it possible for signals generated by the strategy - both for opening and closing positions - to be automatically transmitted to Psyll in the form of webhook requests. This allows you to create a fully autonomous trading system that operates 24/7, reacting to signals in real time.

In practice, the integration process involves adding special conditions to the strategy code that generate notifications when specific market criteria are met. Each alert is assigned content in a JSON format compliant with Psyll's requirements (e.g., containing the fields action, quantity, and symbol) and the platform's webhook address. After publishing the strategy on TradingView and enabling alerts, every time a condition in the strategy is met, it automatically results in an HTTP POST request being sent to Psyll, which triggers the appropriate action on the exchange.

Thanks to this integration, you can:

  • Execute your strategy in a fully automated mode, without manual order placement.
  • Test and optimize your strategy in TradingView, and then smoothly implement it in real-world conditions.
  • Synchronize actions across multiple markets or trading pairs simultaneously.

GitHub

All official repositories, client libraries, supporting tools, and supplementary materials are published on our GitHub profile: https://github.com/psyll. There, you'll find not only the source code but also project documentation, installation instructions, deployment examples, and additional resources for developers.

The repositories are constantly updated and developed to provide users with the latest features and security patches. Each project is released under an open license, so you can freely modify and adapt it to your needs. In the "Issues" section, you can also report bugs, propose new features, or discuss with other developers.

GitHub is the ideal place to start working with Psyll at the code level, track changes in our libraries, and draw inspiration from examples prepared by the community. This allows you to develop your projects faster and fully leverage the possibilities of integration with the Psyll platform.