Pricing Context

The problem pricing contexts solve

Bitwave has default pricing and pricing rules that act as the global default.

This works well until pricing needs to differ:

1. Between wallets
2. Between different types of activity
3. Or between recording, reporting, and revaluation

Global pricing rules alone cannot handle these cases. Pricing contexts were introduced to allow more flexibility without replacing or breaking existing pricing rules.

If a pricing context applies, Bitwave uses it. If it does not, Bitwave continues using global pricing rules.

What is a pricing context?

A pricing context defines how pricing should be handled for a specific purpose. It allows control over:

A: Which price source is used

1. Binance
2. Coinbase
3. CryptoCompare
4. CoinGecko
5. CoinMarketCap
6. Kaiko (coming soon)

B: What price resolution is taken

1. 1 minute
2. 5 minutes
3. 10 minutes
4. 15 minutes
5. 1 hour
6. 12 hours
7. 1 day
8. 7 days
9. 1 month
10. T-1 day
11. T-15 minutes

C: Which pricing method applies

1. Open
2. Close
3. High
4. Low

Pricing contexts can be applied broadly or narrowly, depending on the use case.

Types of pricing contexts

Transaction context

Used when transactions are first recorded.

This allows control over:

1. Pricing timing
2. Price source
3. Pricing method

Changes apply only going forward. Historical transactions are not affected unless repricing is run.

**Reporting context

**Used when balances and reports are generated. Reporting pricing can differ from how transactions were originally recorded.

Revaluation context

Used when asset values are updated after transactions are recorded, including revaluation and impairment-related workflows.

Revaluation does not change how transactions were originally priced unless repricing is run.

How Bitwave decides which pricing to use

Pricing follows a clear order:

1. Check whether a pricing context applies
2. If yes, use that pricing context
3. If not, fall back to global pricing rules

****Pricing Routes

Custom pricing contexts are applied using routes.

A route defines matching conditions and points to one pricing context.

Routes can match based on:

1. Wallet
2. Transaction direction
3. Metadata attached to the transaction

If a route matches, the linked pricing context is used. If no route matches, pricing falls back to the default.

Example: Using Pricing Routes to apply Metadata-based Pricing

An organization uses a single wallet for multiple types of activity. Most transactions in this wallet can use standard pricing, but a specific subset needs different pricing rules.

The requirement is:

1. Apply special pricing only to certain transactions
2. Keep all other transactions unchanged
3. Avoid creating additional wallets

Step 1: Create a pricing context

First, a pricing context is created that defines:

1. The price source
2. The timing used for pricing
3. The pricing method

This context represents how pricing should be done once it is selected.

Step 2: Create a pricing route

Next, a pricing route is created to decide when this context applies.

The route is configured with the following conditions:

1. **Wallet: **Select the wallet where this activity occurs
2. **Direction: **Select the transaction direction (for example, inbound or outbound)
3. **Start and End dates: **Select if pricing context needs to be applied to transactions within a specific date range
4. **Metadata: **Define a key and value that identify the specific type of activity

How the route works

When a transaction is processed, Bitwave checks:

1. Is the transaction in the selected wallet?
2. Does the transaction match the selected direction and date range?
3. Does the transaction contain the specified metadata key and value?

If all conditions match, the pricing context linked to the route is used. If any condition does not match, the route is skipped and pricing falls back to the default.

What happens when pricing changes?

Pricing context changes apply from that point forward.

1. Future pricing uses the updated rules
2. Past pricing remains unchanged
3. Historical pricing changes require running a repricing

This mirrors how global pricing rules behave.

**Visibility and review

For each pricing decision, Bitwave provides visibility into:

1. Whether a pricing context or global rule was used
2. Which route matched, if applicable
3. Why a fallback occurred

Change history

All pricing context changes are recorded.

This includes:

1. What was changed
2. When the change was made

Because this history is preserved, pricing contexts can be adjusted or deleted without losing traceability.

When pricing contexts are useful

Pricing contexts are useful when:

1. Different wallets require different pricing rules
2. A single wallet supports multiple activities
3. Reporting pricing differs from transaction pricing