Skip to content

Improve Https outcalls cost documentation #5565

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 25, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion docs/building-apps/essentials/gas-cost.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,26 @@ The current values of fees are `base-fee` = 5M cycles (or $0.00000668305 USD), `

### HTTPS outcalls

The cost for an HTTPS outcall is calculated using the formula `(3_000_000 + 60_000 * n) * n` for the base fee and `400 * n` each request byte and `800 * n` for each response byte, where `n` is the number of nodes in the subnet.
The cycles cost of an HTTPS outcall request has both a fixed and variable component.
The fixed component accounts for the known overhead associated with an HTTPS outcall, whereas the variable component accounts for the resources consumed during the request.
The cost scales with regard to subnet size.

Currently, these fees are:

```
total_fee = base_fee + size_fee
base_fee = (3_000_000 + 60_000 * n) * n
size_fee = (400 * request_bytes + 800 * max_response_bytes) * n
```

The `request_bytes` includes the entire request, not just the HTTP body:

```
request_size = url.len + transform.name.len + transform.context.len + body.len + header_len
header_len = header_1.name + header_1.value + ... + header_n.name + header_n.value
```

while `max_response_bytes` is either set by the canister or defaults to `2M`.

## Errors related to cycles

Expand Down
12 changes: 1 addition & 11 deletions docs/references/https-outcalls-how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -172,17 +172,7 @@ Developers new to the feature are likely to run into certain problems in the beg

### Pricing

The cycles cost for an HTTPS outcall request has a fixed and variable component. The fixed part accounts for the constant overheads associated with an HTTPS outcall, whereas the variable part charges for the resources consumed during the requests. Just like with other functions, the cost is scaled to account for larger subnets. The current prices can be found [here](/docs/building-apps/essentials/gas-cost).

**Formula:**
```
header_len = header_1.name + header_1.value + ... + header_n.name + header_n.value
request_size = url.len + transform.name.len + transform.context.len + body.len + header_len
http_outcall_cost = per_call_cost + per_request_byte_cost * request_size + per_response_byte_cost * max_response_size
scaling_factor = subnet_size / 13
total_cost = scaling_factor * http_outcall_cost
```

[View the cycles cost for an HTTPS outcall request](/docs/building-apps/essentials/gas-cost#https-outcalls).
The cycles provided with the call must be sufficient for covering the cost of the request; excessive cycles are returned to the caller.

The current pricing is defined to be rather conservative (expensive), and prices may change in the future with the introduction of an update of the pricing model. However, note that an HTTPS outcall with a small response, like the ones used for querying financial APIs, only costs fractions of a USD cent, which is substantially cheaper than fees charged for a call by oracles on most blockchains.
Expand Down