Skip to main content
Price rules allow you to monitor cryptocurrency prices and trigger notifications when specific conditions are met. This guide covers how to create, update, and manage price alert rules.

​
Understanding Price Rules

A price rule consists of:
  • Name: A descriptive identifier for your rule
  • Description: Optional details about the rule’s purpose
  • Instrument: The cryptocurrency pair to monitor (e.g., BTCUSDT, ETHUSDT)
  • Conditions: One or more conditions that trigger the alert
  • Status: Enabled or disabled

​
Condition Types

PriceSignal supports five types of price conditions:
TypeDescriptionExample
PRICETriggers when price reaches a specific valueBTC reaches $50,000
PRICE_PERCENTAGETriggers on percentage changeETH drops 5%
PRICE_ACTIONMonitors price movement patternsPrice crosses moving average
PRICE_CROSSOVERDetects when price crosses a thresholdPrice breaks above resistance
TECHNICAL_INDICATORUses technical indicatorsRSI exceeds 70

​
Creating a Price Rule

1

Authenticate your request

All rule operations require authentication. Ensure you have a valid JWT token from Firebase.
# Include authentication header
Authorization: Bearer <your_firebase_token>
2

Choose your instrument

Get the instrument ID for the cryptocurrency pair you want to monitor:
query GetInstruments {
  instruments {
    edges {
      node {
        entityId
        symbol
        name
      }
    }
  }
}
Supported pairs: BTCUSDT, ETHUSDT (configurable via backend)
3

Define your conditions

Create one or more conditions for your rule. Each condition requires:
  • conditionType: The type of condition
  • value: The threshold or target value
  • additionalValues: JSON string with extra parameters
Example condition structure:
{
  "conditionType": "PRICE",
  "value": 50000.0,
  "additionalValues": "{}"
}
4

Execute the createPriceRule mutation

Use the GraphQL mutation to create your rule:
mutation CreatePriceRule($input: PriceRuleInput!) {
  createPriceRule(input: $input) {
    entityId
    name
    description
    isEnabled
    instrument {
      symbol
    }
    conditions {
      conditionType
      value
      additionalValues
    }
  }
}
Variables:
{
  "input": {
    "name": "BTC Price Alert",
    "description": "Notify when BTC reaches $50k",
    "instrumentId": "<instrument_entity_id>",
    "conditions": [
      {
        "conditionType": "PRICE",
        "value": 50000.0,
        "additionalValues": "{}"
      }
    ]
  }
}

​
Implementation Details

The createPriceRule mutation is implemented in src/PriceSignal/GraphQL/Mutations/PriceRuleMutations.cs:18-65: 
public async Task<PriceRule> CreatePriceRule(
    PriceRuleInput input, 
    AppDbContext dbContext, 
    [Service] IServiceProvider serviceProvider, 
    [Service] RuleCache ruleCache, 
    [Service] IUser user)
{
    if (user.UserIdentifier == null)
    {
        throw new InvalidOperationException("User not found");
    }
    
    var instrument = await dbContext.Instruments
        .FirstOrDefaultAsync(i => i.EntityId == input.InstrumentId);
    if (instrument == null)
    {
        throw new InvalidOperationException("Instrument not found");
    }

    var conditions = input.Conditions.Select(c => new PriceCondition
    {
        ConditionType = c.ConditionType,
        Value = c.Value,
        AdditionalValues = JsonDocument.Parse(c.AdditionalValues)
    }).ToList();
    
    var priceRule = new PriceRule
    {
        Name = input.Name,
        Description = input.Description,
        InstrumentId = instrument.Id,
        Conditions = conditions,
        UserId = user.UserIdentifier
    };

    dbContext.PriceRules.Add(priceRule);
    await dbContext.SaveChangesAsync();
    
    // Add to cache for real-time monitoring
    ruleCache.AddOrUpdateRule(priceRule);
    
    // Update Binance subscriptions
    binanceProcessingService?.UpdateSubscriptionsAsync();

    return priceRule;
}

​
Updating a Price Rule

Modify existing rules using the updatePriceRule mutation: 
mutation UpdatePriceRule($input: PriceRuleInput!) {
  updatePriceRule(input: $input) {
    entityId
    name
    isEnabled
  }
}
Variables: 
{
  "input": {
    "id": "<rule_entity_id>",
    "name": "Updated Rule Name",
    "description": "Updated description",
    "instrumentId": "<instrument_entity_id>",
    "conditions": [
      {
        "conditionType": "PRICE",
        "value": 55000.0,
        "additionalValues": "{}"
      }
    ]
  }
}

​
Enabling/Disabling Rules

Toggle rule status without modifying conditions: 
mutation TogglePriceRule($id: UUID!) {
  togglePriceRule(id: $id) {
    entityId
    isEnabled
  }
}
Variables: 
{
  "id": "<rule_entity_id>"
}
This toggles isEnabled between true and false, and updates the rule cache and Binance subscriptions automatically.

​
Deleting a Price Rule

Permanently remove a rule: 
mutation DeletePriceRule($id: UUID!) {
  deletePriceRule(id: $id) {
    entityId
    name
  }
}
Variables: 
{
  "id": "<rule_entity_id>"
}

​
Querying Your Rules

Retrieve all rules for the authenticated user: 
query GetMyRules {
  priceRules {
    edges {
      node {
        entityId
        name
        description
        isEnabled
        createdAt
        instrument {
          symbol
          name
        }
        conditions {
          conditionType
          value
          additionalValues
        }
      }
    }
  }
}

​
Example: Complete Rule Creation

Here’s a complete example creating a rule that alerts when ETH drops 5%: 
mutation CreateETHDropAlert {
  createPriceRule(input: {
    name: "ETH 5% Drop Alert"
    description: "Alert me when Ethereum drops 5% from current price"
    instrumentId: "<eth_instrument_id>"
    conditions: [{
      conditionType: PRICE_PERCENTAGE
      value: -5.0
      additionalValues: "{\"period\":\"1h\"}"
    }]
  }) {
    entityId
    name
    isEnabled
    conditions {
      conditionType
      value
    }
  }
}

​
How Rules Are Monitored

Once created, your rules are:
  1. Stored in the database for persistence
  2. Loaded into RuleCache for fast evaluation
  3. Monitored by BinancePriceFetcherService which:
    • Subscribes to real-time price feeds from Binance
    • Evaluates conditions on every price update
    • Triggers notifications when conditions are met
The rule engine runs continuously in the background, evaluating all enabled rules against incoming price data.

​
Best Practices

  • Use descriptive names to easily identify rules
  • Start with simple conditions before creating complex multi-condition rules
  • Disable rules you don’t need instead of deleting them
  • Test rules with price thresholds you expect to be reached soon
  • Monitor notification channels to ensure alerts are being delivered

​
Next Steps

Telegram Setup

Configure Telegram to receive your alerts

Real-time Charts

Visualize price movements with live charts

Build docs developers (and LLMs) love

Get started for freeTalk to us