# Currency Handling

## Default: USD

All cloud pricing APIs return prices in USD by default. Unless the user explicitly requests a different currency, return all estimates in USD.

State the currency clearly in the output header:
```
Currency: USD (on-demand list price, no discounts applied)
```

---

## Other Currencies — User Request

When the user asks for a non-USD estimate:

1. Fetch the USD price from the cloud pricing API.
2. Convert using an exchange rate from one of these public sources (WebFetch):
   - **Preferred** — ExchangeRate-API free endpoint: `https://open.er-api.com/v6/latest/USD` (no auth, returns JSON with major currencies).
   - Fallback — European Central Bank daily reference rates: `https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml` (no auth, EUR-denominated).

> **Do not use** Open Exchange Rates (`openexchangerates.org`) for this skill. It requires
> an `app_id` API key. This agent must not accept or store API keys. The two public
> sources above are sufficient for approximation.

### Preferred approach (ExchangeRate-API, no auth)

```
GET https://open.er-api.com/v6/latest/USD
```

Response:
```json
{
  "base_code": "USD",
  "time_last_update_utc": "2026-04-30 00:02:01",
  "rates": {
    "EUR": 0.9245,
    "GBP": 0.7931,
    "JPY": 144.52,
    "AUD": 1.5521,
    "CAD": 1.3802,
    "SGD": 1.3357,
    "HKD": 7.7823,
    "BRL": 5.6741,
    "INR": 83.47
  }
}
```

Usage: `amount_in_target_currency = usd_price × rates[TARGET_CURRENCY_CODE]`

### Labelling converted amounts

Always show both the USD source and the converted amount:

```
Monthly cost: $234.50 USD → €216.84 EUR (ECB rate 2026-04-30: 1 USD = 0.9245 EUR)
```

Never present a converted price without disclosing the exchange rate and its date.

---

## CNY (Chinese Yuan Renminbi)

### When CNY applies

Alibaba Cloud and Tencent Cloud price their mainland China regions in CNY:

| Provider | CNY regions |
|----------|------------|
| Alibaba Cloud | `cn-beijing`, `cn-shanghai`, `cn-zhangjiakou`, `cn-hangzhou`, `cn-shenzhen` |
| Tencent Cloud | `ap-beijing`, `ap-shanghai`, `ap-guangzhou`, `ap-chengdu`, `ap-nanjing` |

International regions for both providers (e.g., `ap-southeast-1`, `ap-singapore`) are priced
in USD and do not require CNY conversion.

### CNY→USD conversion

Use the following formula:

```
usd_value = cny_value / exchange_rate
```

Where `exchange_rate` is the CNY-per-USD rate (e.g., 7.24 means ¥7.24 = $1.00).

### Live conversion rate sources

| Source | URL | Auth | Priority |
|--------|-----|------|---------|
| ExchangeRate-API CNY endpoint (preferred) | `https://v6.exchangerate-api.com/v6/latest/CNY` | None | Primary |
| ECB daily feed | `https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml` | None | Secondary (EUR base; derive CNY via USD cross-rate) |
| PBoC published daily rate (cached fallback) | `https://www.pbc.gov.cn/` | None | Tertiary — use only when primary and secondary are unavailable |

> Do not use sources that require API keys. The agent must not accept or store API keys.

### Mandatory timestamp requirement

Every CNY→USD conversion output must include all three of the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `conversion_rate` | float | The CNY-per-USD rate applied (e.g., `7.24`) |
| `source_url` | string | The URL of the rate service that was used |
| `timestamp` | ISO 8601 | When the rate was fetched (e.g., `2026-05-13T08:00:00Z`) |

If the rate is from a cached or stale source (more than 24 hours old), label it explicitly:
`assumed: 24h stale` and include the staleness note alongside the converted amount.

### Example output label

```
Monthly cost: ¥130 CNY → $17.94 USD
[documentation-based + live-rate: 7.25 CNY/USD @ 2026-05-13T08:00:00Z via https://v6.exchangerate-api.com/v6/latest/CNY]
```

If using a stale cached rate (tertiary fallback):

```
Monthly cost: ¥130 CNY → $17.94 USD
[documentation-based + assumed: 24h stale rate 7.25 CNY/USD — verify at https://www.pbc.gov.cn/]
```

### Labelling CNY amounts

Always show both the CNY source price and the converted USD amount:

```
Monthly cost: ¥600 CNY → $82.76 USD (PBoC/ExchangeRate-API rate 2026-05-13: 1 USD = 7.25 CNY)
```

Never present a converted CNY price without disclosing the exchange rate and its fetch timestamp.

---

## Azure Retail Prices API — Native Currency Support

The Azure Retail Prices API accepts a `currencyCode` query parameter and returns prices in that currency natively:

```
GET https://prices.azure.com/api/retail/prices?api-version=2023-01-01-preview
    &currencyCode=EUR
    &$filter=armRegionName eq 'westeurope' and serviceName eq 'Virtual Machines'
```

Supported currency codes: EUR, GBP, JPY, AUD, CAD, SGD, HKD, BRL, INR, CHF, SEK, DKK, NOK, KRW, MXN, ZAR, and others. Check the API response; unsupported codes return HTTP 400.

When using the Azure API for non-USD estimates, prefer the native `currencyCode` parameter over post-fetch conversion. Note the effective date from the response.

---

## AWS and OCI — USD Only from API

AWS Price List API and OCI pricing API return USD only. For non-USD on these clouds, use the post-fetch conversion approach above.

---

## Rounding

- Show unit prices to 4 decimal places (e.g., $0.0960/hr).
- Show monthly totals to 2 decimal places (e.g., $70.08/month).
- Annual totals: multiply monthly by 12, round to 2 decimal places.

---

## Disclaimer Template

Include in every non-USD estimate:

> Exchange rate applied: {RATE} (source: {SOURCE}, {DATE}). Cloud list prices are in USD; converted amounts are approximate. Actual billing currency and exchange rate depend on your cloud provider agreement and may differ.

# Estimation Workflow

Two distinct modes: **live-environment** (current inventory → cost) and **prototype** (planned spec → cost).

---

## Mode 1 — Live Environment Cost Estimate

Use when: the user wants to know what an existing deployed environment costs based on actual running resources.

### Step 1 — Confirm scope

Before fetching anything:
- Cloud provider(s): AWS / Azure / OCI (or multi-cloud)
- Region(s): confirm exact region; pricing varies
- Resource scope: specific service, entire account/subscription/tenancy, or filtered subset
- Time window: monthly (default) or annual
- Currency: USD (default) or specified

### Step 2 — Inventory

Preferred: user provides a resource list (instance IDs, sizes, quantities).

Fallback: ask user to share a sanitized inventory export:
- AWS: `aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,InstanceType,State.Name]'`
- Azure: `az resource list --query '[].{id:id,type:type,location:location}'`
- OCI: `oci compute instance list --compartment-id <ocid> --all --query 'data[*].{id:id,"shape":shape,"state":"lifecycle-state"}'`

Do not ask for raw API responses with secrets, billing account IDs, or customer-specific metadata.

### Step 3 — Fetch live prices

For each unique (resource-type, region) pair in the inventory:
1. Load `references/pricing-apis.md`
2. Call the appropriate public pricing API via WebFetch
3. Record: unit price, unit of measure, effective date, currency (USD)

### Step 4 — Calculate

For each line item:
```
monthly_cost = unit_price_per_hour × hours_per_month × quantity
hours_per_month = 730  (standard FinOps convention: 365 days × 24 hours / 12)
```

For storage (priced per GB-month):
```
monthly_cost = price_per_gb_month × total_gb × quantity
```

For data transfer (priced per GB):
```
monthly_cost = price_per_gb × estimated_monthly_gb_transferred
```

### Step 5 — Output

Return the line-item table and totals. See SKILL.md "Response minimum" for format.

---

## Mode 2 — Prototype Cost Estimate

Use when: the user wants to estimate cost for a planned architecture before provisioning.

### Step 1 — Collect the spec

Ask the user to describe the planned architecture. Minimum needed:
- Resource types (e.g., EC2 m5.xlarge, Azure Standard_D4s_v3, OCI VM.Standard.E4.Flex)
- Quantities (instance count, GB of storage, expected GB data transfer/month)
- Region(s)
- Operating system / license model (Linux / Windows; affects compute pricing)
- Expected usage hours per month (default: 730 = always-on)

For prototype mode, it is acceptable to use reasonable defaults when the user has not specified every detail. Clearly label every assumed value.

### Step 2 — Decompose into billable components

Typical components for a web application prototype:

| Component | Billable units |
|-----------|---------------|
| Compute (VM / container) | CPU-hours |
| OS / license (Windows, RHEL) | Additional per-hour |
| Managed database | vCPU-hours + storage GB-month + backup storage |
| Object storage | GB stored/month + GET/PUT requests + egress GB |
| Load balancer | Per hour + LCU or data-processed GB |
| Container orchestration | Cluster management fee + node hours |
| Serverless functions | Invocations + GB-seconds |
| Egress / data transfer | GB out to internet |
| Monitoring / logging | GB ingested + GB stored |

Only include components that are in the user's spec. Do not inflate with unused services.

### Step 3 — Fetch live prices

Same as Mode 1 Step 3.

### Step 4 — Calculate

Same as Mode 1 Step 4.

Label every assumed value in the output with `[assumed]`.

### Step 5 — Sensitivity summary

For prototype estimates, include a brief sensitivity section:
- What is the biggest cost driver?
- What assumption has the most uncertainty?
- What would change the estimate by >20% if revised?

Example:
```
Biggest driver: RDS db.r6g.xlarge instance ($0.48/hr × 730 hr = $350/month, 42% of total)
Highest uncertainty: data egress volume — assumed 100 GB/month; at 1 TB/month cost doubles
```

---

## Multi-Cloud Comparison

When comparing AWS vs Azure vs OCI vs Scaleway (or any subset) for the same workload:

1. Map resource types to equivalents across clouds:

| Workload | AWS | Azure | OCI | Scaleway | Gandi | Alibaba Cloud | Tencent Cloud |
|---------|-----|-------|-----|---------|-------|---------------|---------------|
| 4 vCPU / 16 GB VM | m5.xlarge | Standard_D4s_v3 | VM.Standard.E4.Flex (4 OCPU, 16 GB) | GP1-M (4 vCPU, 16 GB) | VPS Business (4 vCPU, 16 GB) | ecs.g7.xlarge (4 vCPU, 16 GiB) | Standard S5.LARGE16 (4 vCPU, 16 GiB) |
| Managed PostgreSQL | RDS PostgreSQL db.t4g.medium | Azure Database for PostgreSQL Flexible | OCI MySQL Database / ADB-S | Scaleway RDB PostgreSQL | Not available (use external managed DB) | RDS for PostgreSQL (Basic / High-Availability) | TencentDB for PostgreSQL |
| Object storage | S3 Standard | Azure Blob Storage LRS | OCI Object Storage | Scaleway OSS | Gandi Object Storage | OSS Standard | COS Standard |
| Container cluster | EKS | AKS | OKE | Scaleway Kapsule | Not available (use self-managed) | ACK (Alibaba Container Service for Kubernetes) | TKE (Tencent Kubernetes Engine) |

2. Fetch prices for each cloud in the user's preferred region(s).
3. Present side-by-side comparison table, USD, monthly.
4. Note: OCI often prices differently for Flex shapes (OCPU + memory separately); adjust comparison accordingly.
5. Note: Scaleway pricing is EUR-native; apply a live EUR/USD exchange rate (see
   [./official-sources.md](./official-sources.md) — Exchange Rate Sources) and display the
   EUR price alongside the converted USD amount. Label the conversion date and rate used.
6. Note: Gandi pricing is available in both EUR and USD via the API. If the user has not
   provided an API key, use the official pricing page and label the estimate as
   `documentation-based`. See [./provider-fallbacks.md](./provider-fallbacks.md) for the
   decision tree.
7. Note: Alibaba Cloud pricing is scrape-based (no public unauthenticated API). All prices
   must be labeled `documentation-based`. For mainland (`cn-*`) regions, prices are in CNY;
   apply a CNY-to-USD conversion with a live rate and timestamp (see
   [./currency-handling.md](./currency-handling.md) — CNY section). International regions
   are priced in USD. See [./provider-fallbacks.md](./provider-fallbacks.md) for the full
   scrape fallback chain.
8. Note: Tencent Cloud pricing is scrape-based (no public unauthenticated API). JavaScript
   rendering may be required on the primary pricing page. All prices must be labeled
   `documentation-based`. For mainland (`ap-beijing`, `ap-shanghai`, `ap-guangzhou`) regions,
   prices are in CNY; apply a CNY-to-USD conversion with a live rate and timestamp (see
   [./currency-handling.md](./currency-handling.md) — CNY section). International regions
   are priced in USD. See [./provider-fallbacks.md](./provider-fallbacks.md) for the full
   scrape fallback chain.

### Scaleway reference instance for comparison

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Scaleway | — |
| Instance type | PRO2-XS | Smallest production-grade Scaleway instance |
| vCPU | 2 | — |
| RAM | 8 GiB | — |
| Root storage | 20 GiB SSD (local) | Included in instance price |
| Region | fr-par (Paris, France) | eu-fr |
| Monthly estimate | ~€10–14/month | `documentation-based` (official pricing page) |
| API reference | `instances_b_ssd_x86_64_pro2_xs` | beta billing API SKU name |
| USD note | Convert using live EUR/USD rate | See official-sources.md |

> **Provenance label**: `documentation-based` — price derived from the official Scaleway
> pricing page (https://www.scaleway.com/en/pricing/). The beta billing API requires auth;
> if a live fetch succeeds, upgrade the label to `live-price` and include the timestamp.

### Gandi reference instance for comparison

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Gandi | — |
| Instance type | VPS Start 2 | Smallest standard Gandi VPS tier |
| vCPU | 1 | — |
| RAM | 2 GiB | — |
| Storage | 20 GiB SSD | Included in instance price |
| Region | eu (EU default) | — |
| Monthly estimate | ~€2.99/month | `documentation-based` (official pricing page) |
| USD note | EUR price shown; convert using live EUR/USD rate | See official-sources.md |

> **Provenance label**: `documentation-based` — price derived from the official Gandi
> pricing page (https://www.gandi.net/domain/pricing). If the user supplies an API key
> in the request, call `https://api.gandi.net/v5/price-list` with
> `Authorization: Apikey <key>` and upgrade the label to `live-price`. See
> [./provider-fallbacks.md](./provider-fallbacks.md) for the full decision tree.

### Alibaba Cloud ECS reference instance for comparison

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Alibaba Cloud | — |
| Instance type | ecs.t6-c1m1.small | Entry-level burstable instance |
| vCPU | 1 | — |
| RAM | 1 GiB | — |
| Storage | 20 GiB cloud disk | Not included; billed separately |
| Region | cn-shanghai (Shanghai, Mainland China) | CNY region |
| Monthly estimate (CNY) | ~¥130 CNY/month | `documentation-based` |
| Monthly estimate (USD) | ~$18 USD/month | `documentation-based` + live-rate conversion required |
| Currency note | CNY price shown; convert using live CNY/USD rate with timestamp | See currency-handling.md — CNY section |

> **Provenance label**: `documentation-based` — price derived from the official Alibaba Cloud
> pricing page (https://www.alibabacloud.com/cloud-computing/pricing). No live API is
> available without authentication. CNY-to-USD conversion must use a live rate with timestamp;
> see [./currency-handling.md](./currency-handling.md) — CNY section. Scrape-based; price may
> be stale if the page structure has changed. See
> [./provider-fallbacks.md](./provider-fallbacks.md) for the full fallback chain.

### Tencent Cloud CVM reference instance for comparison

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Tencent Cloud | — |
| Instance type | Standard S5.LARGE8 | Standard compute instance |
| vCPU | 2 | — |
| RAM | 8 GiB | — |
| Storage | 50 GiB cloud disk | Not included; billed separately |
| Region | ap-beijing (Beijing, Mainland China) | CNY region |
| Monthly estimate (CNY) | ~¥600 CNY/month | `documentation-based` |
| Monthly estimate (USD) | ~$83 USD/month | `documentation-based` + live-rate conversion required |
| Currency note | CNY price shown; convert using live CNY/USD rate with timestamp | See currency-handling.md — CNY section |

> **Provenance label**: `documentation-based` — price derived from the official Tencent Cloud
> CVM pricing page (https://cloud.tencent.com/product/cvm/pricing). No live API is available
> without authentication. JavaScript rendering may be required to resolve dynamically loaded
> price tables. CNY-to-USD conversion must use a live rate with timestamp; see
> [./currency-handling.md](./currency-handling.md) — CNY section. See
> [./provider-fallbacks.md](./provider-fallbacks.md) for the full fallback chain.

---

## Estimate Quality Labels

Always label estimates with one of:
- `live-price`: price fetched from API in this session with timestamp
- `documentation-based`: price from official pricing page docs (may be weeks old)
- `assumed`: value not provided by user and not fetched; based on typical pattern
- `excluded`: component not included in estimate; state why

# Official Sources

Authoritative pricing documentation for each cloud provider. Use these as ground truth when live API results are ambiguous or unavailable.

---

## AWS

| Resource | URL |
|----------|-----|
| Price List API overview | `https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/price-changes.html` |
| Price List API reference | `https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/using-ppslong.html` |
| EC2 pricing page | `https://aws.amazon.com/ec2/pricing/on-demand/` |
| RDS pricing page | `https://aws.amazon.com/rds/pricing/` |
| S3 pricing page | `https://aws.amazon.com/s3/pricing/` |
| Lambda pricing page | `https://aws.amazon.com/lambda/pricing/` |
| EKS pricing page | `https://aws.amazon.com/eks/pricing/` |
| Fargate pricing page | `https://aws.amazon.com/fargate/pricing/` |
| Data Transfer pricing | `https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer` |
| Price List service index | `https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/index.json` |
| AWS Pricing Calculator | `https://calculator.aws/pricing/2/home` |

## Azure

| Resource | URL |
|----------|-----|
| Retail Prices API docs | `https://learn.microsoft.com/en-us/rest/api/cost-management/retail-prices/azure-retail-prices` |
| VM pricing page | `https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/` |
| AKS pricing page | `https://azure.microsoft.com/en-us/pricing/details/kubernetes-service/` |
| Azure SQL pricing | `https://azure.microsoft.com/en-us/pricing/details/azure-sql-database/single/` |
| Azure PostgreSQL Flexible | `https://azure.microsoft.com/en-us/pricing/details/postgresql/flexible-server/` |
| Blob Storage pricing | `https://azure.microsoft.com/en-us/pricing/details/storage/blobs/` |
| Bandwidth pricing | `https://azure.microsoft.com/en-us/pricing/details/bandwidth/` |
| Azure Functions pricing | `https://azure.microsoft.com/en-us/pricing/details/functions/` |
| Azure Pricing Calculator | `https://azure.microsoft.com/en-us/pricing/calculator/` |
| Cost Management overview | `https://learn.microsoft.com/en-us/azure/cost-management-billing/cost-management-billing-overview` |

## OCI

| Resource | URL |
|----------|-----|
| OCI Price List (HTML) | `https://www.oracle.com/cloud/price-list.html` |
| OCI Cost Analysis overview | `https://docs.oracle.com/en-us/iaas/Content/Billing/Concepts/costanalysisoverview.htm` |
| OCI Compute shapes | `https://docs.oracle.com/en-us/iaas/Content/Compute/References/computeshapes.htm` |
| OCI Autonomous Database pricing | `https://www.oracle.com/autonomous-database/pricing/` |
| OCI Object Storage pricing | `https://www.oracle.com/cloud/storage/object-storage/pricing/` |
| OCI Networking / egress pricing | `https://www.oracle.com/cloud/networking/pricing/` |
| OCI Cloud Estimator (calculator) | `https://cloudestimator.oracle.com` |
| OCI Cost and Usage API | `https://docs.oracle.com/en-us/iaas/Content/Billing/Tasks/costanalysis_topic-create_report.htm` |

## Scaleway

| Resource | URL | Status | Currency |
|----------|-----|--------|---------|
| Official pricing page | `https://www.scaleway.com/en/pricing/` | Production, public, no auth | EUR |
| Billing API reference | `https://developer.scaleway.com/en/products/billing/api/` | Beta (auth required) | EUR |
| Developer documentation | `https://www.scaleway.com/en/developers/api/` | Production | N/A |
| Changelog | `https://www.scaleway.com/en/changelog/` | Production | N/A |
| API key management | `https://console.scaleway.com/iam/api-keys` | Production | N/A |
| Scaleway Pricing Calculator | `https://www.scaleway.com/en/cost-calculator/` | Production | EUR |

> Scaleway pricing is EUR-native. No USD pricing is available via the API. Use a live
> exchange rate source (see Exchange Rate Sources below) to convert to USD or other
> currencies. The `billing/v2beta1` API endpoint requires a Scaleway IAM token; the
> official pricing page is the reliable unauthenticated fallback. Verify beta API status
> at https://www.scaleway.com/en/changelog/ before any integration.

## Gandi

| Resource | URL | Status | Currency | Key management |
|----------|-----|--------|---------|----------------|
| Official pricing page | `https://www.gandi.net/domain/pricing` | Production, public, no auth | EUR, USD | N/A — public page |
| Price List API | `https://api.gandi.net/v5/price-list` | Production, auth required | EUR, USD | User-provided API key (never stored by agent) |
| API documentation | `https://api.gandi.net/docs/` | Production | N/A | N/A |
| LiveDNS documentation | `https://doc.livedns.gandi.net/` | Production | N/A | N/A |
| API key management | `https://account.gandi.net/en/users/api-keys` | Production | N/A | User manages their own keys |

> Gandi pricing is available in both EUR and USD via the API response. The Price List API
> requires a user-provided API key (`Authorization: Apikey <key>`). The agent never prompts
> for, stores, or logs API keys. If no key is supplied in the request, fall back to the
> official pricing page and label the estimate as `documentation-based`.
> See [./provider-fallbacks.md](./provider-fallbacks.md) for the full decision tree.

## Alibaba Cloud

| Resource | URL | Status | Currency |
|----------|-----|--------|---------|
| Official pricing page | `https://www.alibabacloud.com/cloud-computing/pricing` | Production, scrape-based (HTML parser required) | CNY (mainland), USD (International endpoint) |
| Cost calculator | `https://www.alibabacloud.com/price-calculator` | Production, scrape-based (HTML parser required) | CNY (mainland), USD (International endpoint) |
| ECS product page | `https://www.alibabacloud.com/product/ecs` | Production | N/A |
| RDS product page | `https://www.alibabacloud.com/product/apsaradb-for-rds` | Production | N/A |
| OSS product page | `https://www.alibabacloud.com/product/oss` | Production | N/A |

> Alibaba Cloud has no public unauthenticated pricing API. Pricing is obtained by scraping
> the official pricing page via WebFetch. An HTML parser is required; the page does not
> expose a JSON feed. All prices must be labeled `documentation-based`. For mainland
> (`cn-*`) regions, prices are in CNY; apply a CNY-to-USD conversion with a live rate and
> timestamp (see CNY section below). International (`ap-*`, `us-*`, `eu-*`) regions are
> priced in USD. See [./provider-fallbacks.md](./provider-fallbacks.md) for the full
> scrape fallback chain.

## Tencent Cloud

| Resource | URL | Status | Currency |
|----------|-----|--------|---------|
| CVM pricing page | `https://cloud.tencent.com/product/cvm/pricing` | Production, scrape-based (JavaScript rendering may be required) | CNY (mainland), USD (International endpoint) |
| Cost calculator | `https://cloud.tencent.com/price` | Production, scrape-based (JavaScript rendering may be required) | CNY (mainland), USD (International endpoint) |
| TencentDB product page | `https://cloud.tencent.com/product/cdb` | Production | N/A |
| COS product page | `https://cloud.tencent.com/product/cos` | Production | N/A |
| CLB product page | `https://cloud.tencent.com/product/clb` | Production | N/A |

> Tencent Cloud has no public unauthenticated pricing API. Pricing is obtained by scraping
> the official CVM pricing page via WebFetch. JavaScript rendering may be required to
> resolve dynamically loaded price tables. All prices must be labeled `documentation-based`.
> For mainland (`ap-beijing`, `ap-shanghai`, `ap-guangzhou`, and other mainland) regions,
> prices are in CNY; apply a CNY-to-USD conversion with a live rate and timestamp (see CNY
> section below). International regions are priced in USD. See
> [./provider-fallbacks.md](./provider-fallbacks.md) for the full scrape fallback chain.

## Exchange Rate Sources

| Source | URL | Auth | Notes |
|--------|-----|------|-------|
| ExchangeRate-API (preferred) | `https://open.er-api.com/v6/latest/USD` | None | Major currencies; updated daily |
| ECB daily reference rates (fallback) | `https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml` | None | EUR-denominated; reliable but limited currency set |
| ExchangeRate-API CNY endpoint | `https://v6.exchangerate-api.com/v6/latest/CNY` | None | CNY-denominated; use for CNY→USD conversion; updated daily |
| PBoC daily rate (CNY cached fallback) | `https://www.pbc.gov.cn/` | None | People's Bank of China published daily rate; use when ExchangeRate-API is unavailable |

Do not use sources that require API keys (e.g., openexchangerates.org). The agent must not accept or store API keys.

---

## Grounding Rule

When a live API fetch returns a price that differs significantly from the official pricing page, prefer the live API result (it is more current) but note the discrepancy. If the API result appears clearly wrong (e.g., $0.00 or orders-of-magnitude off), fall back to the official pricing page and label the estimate as `documentation-based`.

# Pricing APIs

Public pricing endpoints for AWS, Azure, OCI, Scaleway, Gandi, Alibaba Cloud, and Tencent Cloud.
Alibaba and Tencent have no unauthenticated public API; pricing is obtained via web scrape.

---

## AWS — Price List API

**Base URL**: `https://pricing.us-east-1.amazonaws.com`

No authentication. No API key. No AWS account needed.

### Service index

```
GET https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/index.json
```

Returns a JSON map of all service codes and their per-service offer file paths.

### Per-service, per-region offer file

```
GET https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/{serviceCode}/current/{regionCode}/index.json
```

Examples:
```
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonEC2/current/us-east-1/index.json
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonRDS/current/us-east-1/index.json
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonS3/current/us-east-1/index.json
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonECS/current/us-east-1/index.json
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AWSLambda/current/us-east-1/index.json
```

⚠️ These files are very large (EC2 index is tens of MB). Use the CSV variant for scripting:
```
https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/{serviceCode}/current/{regionCode}/index.csv
```

### Key response fields (products + terms)

```json
{
  "products": {
    "<sku>": {
      "sku": "...",
      "productFamily": "Compute Instance",
      "attributes": {
        "instanceType": "m5.xlarge",
        "vcpu": "4",
        "memory": "16 GiB",
        "operatingSystem": "Linux",
        "tenancy": "Shared",
        "location": "US East (N. Virginia)"
      }
    }
  },
  "terms": {
    "OnDemand": {
      "<sku>.<offerTermCode>": {
        "priceDimensions": {
          "<rateCode>": {
            "unit": "Hrs",
            "pricePerUnit": { "USD": "0.1920000000" },
            "description": "$0.192 per On Demand Linux m5.xlarge Instance Hour"
          }
        }
      }
    }
  }
}
```

### Common service codes

| Service | Code |
|---------|------|
| EC2 | `AmazonEC2` |
| RDS | `AmazonRDS` |
| S3 | `AmazonS3` |
| Lambda | `AWSLambda` |
| ECS / Fargate | `AmazonECS` |
| EKS | `AmazonEKS` |
| ElastiCache | `AmazonElastiCache` |
| CloudFront | `AmazonCloudFront` |
| DynamoDB | `AmazonDynamoDB` |
| Data Transfer | `AWSDataTransfer` |

### AWS region codes (selected)

| Region | Code |
|--------|------|
| US East (N. Virginia) | `us-east-1` |
| US West (Oregon) | `us-west-2` |
| EU (Ireland) | `eu-west-1` |
| EU (Frankfurt) | `eu-central-1` |
| AP (Singapore) | `ap-southeast-1` |
| AP (Tokyo) | `ap-northeast-1` |

---

## Azure — Retail Prices API

**Base URL**: `https://prices.azure.com/api/retail/prices`

No authentication. No API key. No Azure subscription needed.

### Basic request

```
GET https://prices.azure.com/api/retail/prices?api-version=2023-01-01-preview
```

### With OData filter

```
GET https://prices.azure.com/api/retail/prices?api-version=2023-01-01-preview&$filter={filter}
```

Filter examples:
```
armRegionName eq 'eastus' and skuName eq 'D2s v3' and priceType eq 'Consumption'
armRegionName eq 'eastus' and serviceName eq 'Virtual Machines' and contains(skuName, 'D2s')
armRegionName eq 'westeurope' and serviceName eq 'Azure Database for PostgreSQL'
armRegionName eq 'eastus' and serviceName eq 'Azure Kubernetes Service'
armRegionName eq 'eastus' and serviceName eq 'Storage' and skuName eq 'LRS Data Stored'
```

### Key response fields

```json
{
  "Items": [
    {
      "currencyCode": "USD",
      "tierMinimumUnits": 0.0,
      "retailPrice": 0.096,
      "unitPrice": 0.096,
      "armRegionName": "eastus",
      "location": "US East",
      "effectiveStartDate": "2024-06-01T00:00:00Z",
      "meterId": "...",
      "meterName": "D2s v3",
      "productId": "...",
      "skuId": "...",
      "productName": "Virtual Machines DSv3 Series",
      "skuName": "D2s v3",
      "serviceName": "Virtual Machines",
      "serviceFamily": "Compute",
      "unitOfMeasure": "1 Hour",
      "type": "Consumption",
      "isPrimaryMeterRegion": true,
      "armSkuName": "Standard_D2s_v3"
    }
  ],
  "NextPageLink": "...",
  "Count": 1
}
```

### Key filter fields

| Field | Purpose | Example |
|-------|---------|---------|
| `armRegionName` | Azure region | `eastus`, `westeurope`, `southeastasia` |
| `serviceName` | Service category | `Virtual Machines`, `Storage`, `Azure Kubernetes Service` |
| `skuName` | SKU identifier | `D2s v3`, `P10`, `LRS Data Stored` |
| `priceType` | Pricing model | `Consumption` (pay-as-you-go), `Reservation` |
| `armSkuName` | ARM SKU name (exact) | `Standard_D2s_v3` |

### Azure region codes (selected)

| Region | `armRegionName` |
|--------|----------------|
| East US | `eastus` |
| West US 2 | `westus2` |
| West Europe | `westeurope` |
| North Europe | `northeurope` |
| Southeast Asia | `southeastasia` |
| Japan East | `japaneast` |

---

## OCI — Public Pricing API

**Base URL**: `https://apexapps.oracle.com/pls/apex/cloudestimator/r/api`

No authentication required for public list prices.

### All prices endpoint

```
GET https://apexapps.oracle.com/pls/apex/cloudestimator/r/api/prices
```

Returns a JSON array with all OCI service SKUs and their list prices.

### Key response fields

```json
{
  "items": [
    {
      "partNumber": "B88317",
      "displayName": "VM.Standard.E4.Flex - OCPU",
      "currencyCodeLocalizations": [
        {
          "currencyCode": "USD",
          "prices": [
            {
              "model": "PAY_AS_YOU_GO",
              "value": "0.025",
              "unit": "OCPU Per Hour"
            }
          ]
        }
      ]
    }
  ]
}
```

### Alternative: Oracle Cloud Pricing page JSON

```
GET https://www.oracle.com/a/ocom/docs/cloud/oci-price-list.json
```

This is the machine-readable version of the Oracle Cloud Price List. Structure may vary by release.

### Oracle pricing page (human-readable)

```
https://www.oracle.com/cloud/price-list.html
```

### OCI shape pricing pattern

OCI Flex VMs charge separately per OCPU and per GB of memory:
- Compute: OCPU-hour rate × number of OCPUs
- Memory: GB-hour rate × number of GB RAM
- Standard shapes (non-Flex): flat hourly rate per shape

### OCI regions for pricing context

OCI pricing is generally region-independent for compute (same price globally), but data egress and some services do vary. Always confirm whether the target workload has significant egress.

---

## Scaleway — Billing API (beta) / Pricing Page

**Stable fallback**: `https://www.scaleway.com/en/pricing/`

The Scaleway billing catalog API was in active beta as of mid-2025. Until it reaches GA,
treat the official pricing page as the authoritative source for documentation-based estimates.
The beta endpoint is documented below for completeness.

> **Note**: Scaleway pricing is EUR-native. USD conversion must be handled separately using
> a live exchange rate source (see [./official-sources.md](./official-sources.md) — Exchange
> Rate Sources). Always display the EUR price first, then the converted amount with the
> conversion date and rate used.

### Beta billing catalog endpoint

```
GET https://api.scaleway.com/billing/v2beta1/products
X-Auth-Token: <IAM-API-key>
```

Requires a valid Scaleway IAM API key with at minimum `billing:read` permission scope.

### Key response fields (beta)

```json
{
  "products": [
    {
      "name": "instances_b_ssd_x86_64_pro2_xs",
      "display_name": "Production PRO2-XS",
      "region": "fr-par",
      "price": {
        "currency_code": "EUR",
        "units": 0,
        "nanos": 4300000
      },
      "unit_of_measure": "hour"
    }
  ]
}
```

> **Stability warning**: The `billing/v2beta1` endpoint shape may change before GA.
> Always check https://www.scaleway.com/en/changelog/ for updates before integrating.

### Supported resource types (beta coverage)

| Category | Examples |
|----------|---------|
| Compute (Instances) | PRO2, DEV1, GP1 series |
| Block Storage (SBS) | BSSD volumes |
| Object Storage | Scaleway OSS |
| Managed Database (RDB) | PostgreSQL, MySQL managed instances |
| Kubernetes (Kapsule) | Node pool billing |
| Serverless Functions | Invocation + GB-second billing |

### Authentication

| Attribute | Value |
|-----------|-------|
| Method | `X-Auth-Token` header |
| Credential | Scaleway IAM API key (`SCALEWAY_API_KEY`) |
| Minimum scope | `billing:read` |
| Key creation | https://console.scaleway.com/iam/api-keys |

### Rate limits

| Attribute | Value |
|-----------|-------|
| Global limit | ~60 requests/minute (per-route limits not separately documented) |
| Recommended strategy | Single catalog fetch per session; cache results |

### Scaleway region codes

| Region | Code |
|--------|------|
| Paris (France) | `fr-par` |
| Amsterdam (Netherlands) | `nl-ams` |
| Warsaw (Poland) | `pl-waw` |

---

## Gandi — Price List API

**Base URL**: `https://api.gandi.net/v5`

> **Authentication required.** Gandi pricing is not available unauthenticated.
> The agent never stores or logs API keys. User must supply the key explicitly
> in the request. See [../references/provider-fallbacks.md](./provider-fallbacks.md)
> for the full decision tree.

### Price list endpoint

```
GET https://api.gandi.net/v5/price-list
Authorization: Apikey <user-provided-key>
```

**Critical:** Replace `<user-provided-key>` with the key the user explicitly
provided in the current request. Never prompt for credentials and never store
or log any key value.

### Key response fields

```json
[
  {
    "product": {
      "type": "instance",
      "name": "web-server-start2"
    },
    "unit_price": [
      {
        "currency": "EUR",
        "duration": "monthly",
        "price": "2.99"
      },
      {
        "currency": "USD",
        "duration": "monthly",
        "price": "3.27"
      }
    ],
    "description": "VPS Start 2 — 1 vCPU / 2 GB RAM / 20 GB SSD"
  }
]
```

### Authentication

| Attribute | Value |
|-----------|-------|
| Method | `Authorization: Apikey <key>` header |
| Credential | User-provided API key (never stored by agent) |
| Key creation | https://account.gandi.net/en/users/api-keys |
| Fallback if no key | Use official pricing page (label: `documentation-based`) |

### Rate limits

| Attribute | Value |
|-----------|-------|
| Global limit | 100 requests/second |
| Recommended strategy | Single fetch per session; cache results in-context |

### Supported resource types

| Category | Examples |
|----------|---------|
| VPS (Simple Hosting / Cloud) | Start 2, Pro, Business tiers |
| Domain names | TLD-specific pricing (varies per extension) |
| DNS (LiveDNS) | Included with domain; no separate charge |
| Email | Gandi Mail per-mailbox pricing |
| SSL Certificates | DV and EV certificate pricing |
| Object Storage / CDN | Pay-per-GB storage and transfer |

### Gandi currency note

Gandi prices are available in **EUR** and **USD** via the API response.
Always display the EUR price first when both are present. If only one currency
is returned, convert using a live exchange rate (see
[./official-sources.md](./official-sources.md) — Exchange Rate Sources).

---

## Alibaba Cloud — Scrape-Based Pricing

**No public unauthenticated pricing API exists for Alibaba Cloud.**

Pricing is obtained by scraping the official pricing page. All estimates derived
from this source must be labeled `documentation-based`. See
[./provider-fallbacks.md](./provider-fallbacks.md) for the full scrape fallback chain.

### Primary pricing source

```
https://www.alibabacloud.com/cloud-computing/pricing
```

HTML page containing product cards and pricing zones per region.
An HTML parser is required; the page does not expose a JSON feed.

### Cost calculator (secondary source)

```
https://www.alibabacloud.com/price-calculator
```

Use as a fallback when the primary pricing page cannot be parsed.

### Authentication

None required. Public page, no API key.

### Rate limits

No explicit rate limit published. Treat as a standard web scrape:
- Do not send more than one request per session for pricing data.
- Do not retry aggressively on failure; fall back to cached data instead.

### Regions supported

| Region type | Region codes |
|-------------|-------------|
| Mainland China (CNY) | `cn-beijing`, `cn-shanghai`, `cn-zhangjiakou`, `cn-hangzhou`, `cn-shenzhen` |
| Asia-Pacific (USD) | `ap-southeast-1` (Singapore), `ap-northeast-1` (Tokyo), `ap-southeast-5` (Jakarta) |
| Other International (USD) | `us-west-1` (Silicon Valley), `eu-central-1` (Frankfurt) |

> **Currency note**: Mainland `cn-*` regions are priced in CNY. International `ap-*` and
> other non-mainland regions are priced in USD. Apply CNY-to-USD conversion for mainland
> estimates; see [./currency-handling.md](./currency-handling.md) — CNY section.

### Supported products

| Product | Description |
|---------|-------------|
| ECS | Elastic Compute Service (virtual machines) |
| RDS | Relational Database Service (managed database) |
| OSS | Object Storage Service |
| CDN | Content Delivery Network |
| SLB | Server Load Balancer |

---

## Tencent Cloud — Scrape-Based Pricing

**No public unauthenticated pricing API exists for Tencent Cloud.**

Pricing is obtained by scraping the official pricing page. JavaScript rendering
may be required for some product pages. All estimates must be labeled
`documentation-based`. See [./provider-fallbacks.md](./provider-fallbacks.md)
for the full scrape fallback chain.

### Primary pricing source

```
https://cloud.tencent.com/product/cvm/pricing
```

CVM (Cloud Virtual Machine) pricing page. JavaScript rendering may be required
to resolve dynamically loaded price tables.

### Cost calculator (secondary source)

```
https://cloud.tencent.com/price
```

Use as a fallback when the primary pricing page cannot be parsed.

### Authentication

None required. Public page, no API key.

### Rate limits

No explicit rate limit published. Treat as a standard web scrape:
- Do not send more than one request per session for pricing data.
- Do not retry aggressively on failure; fall back to cached data instead.

### Regions supported

| Region type | Region codes |
|-------------|-------------|
| Mainland China (CNY) | `ap-beijing`, `ap-shanghai`, `ap-guangzhou`, `ap-chengdu`, `ap-nanjing` |
| Asia-Pacific International (USD) | `ap-singapore`, `ap-tokyo`, `ap-seoul`, `ap-bangkok`, `ap-mumbai` |
| Other International (USD) | `na-ashburn` (East US), `eu-frankfurt` (Germany) |

> **Currency note**: Mainland `ap-beijing`, `ap-shanghai`, `ap-guangzhou` (and other
> mainland regions) are priced in CNY. International regions are priced in USD. Apply
> CNY-to-USD conversion for mainland estimates; see
> [./currency-handling.md](./currency-handling.md) — CNY section.

### Supported products

| Product | Description |
|---------|-------------|
| CVM | Cloud Virtual Machine (compute instances) |
| TencentDB | Managed relational database (MySQL, PostgreSQL, etc.) |
| COS | Cloud Object Storage |
| CLB | Cloud Load Balancer |
| TKE | Tencent Kubernetes Engine |

---

## Pricing API Comparison

| Feature | AWS | Azure | OCI | Scaleway | Gandi | Alibaba | Tencent |
|---------|-----|-------|-----|---------|-------|---------|---------|
| Auth required | No | No | No | Yes (IAM token) | Yes (user-provided key) | No (scrape) | No (scrape) |
| Filter by region | Yes (URL path) | Yes (OData) | N/A (global) | Yes (response field) | N/A (global list) | N/A (parse page) | N/A (parse page) |
| Filter by SKU | Via JSON parse | OData `skuName` | JSON parse | JSON parse | JSON parse | HTML parse | HTML parse |
| Unit of measure | Per hour | Per hour | Per hour / OCPU | Per hour | Per month (primary) | Per hour / month | Per hour / month |
| Currency in response | USD only | USD (+ native via param) | USD | EUR only | EUR and USD | CNY (mainland), USD (intl) | CNY (mainland), USD (intl) |
| Real-time | Yes | Yes | Yes | Beta (stability low-medium) | Yes (auth required) | No (scrape, may be stale) | No (scrape, may be stale) |
| Notes | Large files; prefer region-scoped | Best developer experience; OData is powerful | Flat list; Flex shapes split OCPU + memory | Beta endpoint; use pricing page as fallback; EUR conversion required | User must supply API key; fallback to docs page if no key provided | Scrape-based; CNY conversion required for mainland regions; label `documentation-based` | Scrape-based; JS rendering may be needed; CNY conversion required for mainland regions; label `documentation-based` |

---

## WebFetch Usage Notes

When calling these endpoints via WebFetch:
- AWS EC2 `index.json` for a single region is very large. Fetch the CSV variant or use the JSON and filter in-context.
- Azure API returns paginated results; follow `NextPageLink` if present.
- OCI API returns a single large array; filter by `displayName` substring or `partNumber` after fetch.
- Scaleway billing API (`/billing/v2beta1/products`) requires an `X-Auth-Token` header. If no token is available, fall back to the official pricing page and label the estimate as `documentation-based`. The beta endpoint may return `404` or an undocumented error shape before GA.
- Gandi price list API (`/v5/price-list`) requires `Authorization: Apikey <key>`. If the user has not provided a key in the current request, do not prompt — fall back to the official pricing page (https://www.gandi.net/domain/pricing) and label the estimate as `documentation-based`. If a user-provided key is present, log: "User-provided API key received; using live pricing. Key will not be stored." then discard the key after the fetch.
- Alibaba Cloud pricing page (`https://www.alibabacloud.com/cloud-computing/pricing`) is scrape-based; no JSON API exists. Parse HTML product cards. If the page structure has changed or the fetch fails, fall back to the price calculator page, then to a cached documentation-based estimate. Label all Alibaba prices as `documentation-based`. For mainland (`cn-*`) regions, always apply a CNY-to-USD conversion with a live rate and timestamp.
- Tencent Cloud pricing page (`https://cloud.tencent.com/product/cvm/pricing`) is scrape-based; JavaScript rendering may be required. If the primary page fails, fall back to `https://cloud.tencent.com/price`, then to a cached documentation-based estimate. Label all Tencent prices as `documentation-based`. For mainland (`ap-beijing`, `ap-shanghai`, `ap-guangzhou`) regions, always apply a CNY-to-USD conversion with a live rate and timestamp.
- If a fetch fails (network timeout, 403, 429), label the result as `fetch-failed` and fall back to documentation-based estimate with explicit uncertainty warning.

# Provider Fallbacks

Decision tree for each provider: when to use a live API versus cached documentation pricing.
Used in conjunction with [./pricing-apis.md](./pricing-apis.md) and
[./official-sources.md](./official-sources.md).

---

## Fallback Principle

Every provider follows the same three-tier priority:

```
1. Live API   — real-time prices; highest accuracy; label: live-price
2. Scrape     — fetch official pricing page via WebFetch; label: documentation-based
3. Cached docs — static pricing from this reference file; label: documentation-based (stale)
```

Use the highest tier available given the request context. Always attach a provenance label
and, for live prices, the response timestamp.

---

## Security Rules (All Providers)

These rules apply without exception across every provider and every fallback tier:

- **Never prompt users for credentials.** If a key is needed and not provided, drop to the
  next fallback tier silently.
- **If the user explicitly includes a key in their request**, use it once for the live API
  call, then discard it. Log the following message and nothing else about the key:
  > "User-provided API key received; using live pricing. Key will not be stored."
- **Never log or echo the key value itself.** Do not include it in intermediate results,
  debug output, or citations.
- **Never store, cache, or carry a key across turns.** Each request is a fresh context;
  any key from a prior turn must not be assumed to be present.
- **Label all outputs** with the correct provenance tier. A `documentation-based` label is
  not a failure — it is honest and expected when no key is available.

---

## Gandi

### Decision tree

```
Request arrives
    │
    ├─ Does the request contain an explicit user-provided Gandi API key?
    │       │
    │       ├─ YES → Live API path (Tier 1)
    │       │         Log: "User-provided API key received; using live pricing. Key will not be stored."
    │       │         Call: GET https://api.gandi.net/v5/price-list
    │       │               Authorization: Apikey <user-provided-key>
    │       │         On success  → label result live-price; include response timestamp
    │       │         On failure  → log HTTP status; fall through to Tier 2
    │       │         After fetch → discard key; do not retain across turns
    │       │
    │       └─ NO  → Documentation path (Tier 2)
    │                 Fetch: https://www.gandi.net/domain/pricing  (WebFetch, no auth)
    │                 On success  → label result documentation-based
    │                 On failure  → use Tier 3 cached reference below
    │
    └─ END
```

### Tier 1 — Live API

| Attribute | Value |
|-----------|-------|
| Endpoint | `https://api.gandi.net/v5/price-list` |
| Auth header | `Authorization: Apikey <user-provided-key>` |
| Rate limit | 100 requests/second |
| Response currency | EUR and USD (both present) |
| Provenance label | `live-price` |
| Post-fetch action | Discard key; never carry across turns |

### Tier 2 — Official Pricing Page (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://www.gandi.net/domain/pricing` |
| Auth required | No |
| Provenance label | `documentation-based` |
| Frequency note | Fetch at request time; do not rely on cached page content |

### Tier 3 — Cached Reference (static fallback of last resort)

Use only when both Tier 1 and Tier 2 fetches fail.

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Gandi | — |
| Instance type | VPS Start 2 | Smallest standard VPS tier |
| vCPU | 1 | — |
| RAM | 2 GiB | — |
| Storage | 20 GiB SSD | Included in instance price |
| Region | eu (EU default) | — |
| Monthly estimate | ~€2.99/month | `documentation-based` (stale; verify before use) |
| USD note | Convert using live EUR/USD rate | See official-sources.md — Exchange Rate Sources |

> Always note in the output that this figure is a static cached reference and may not
> reflect the current price. Direct the user to https://www.gandi.net/domain/pricing to
> verify.

---

## Scaleway

### Decision tree

```
Request arrives
    │
    ├─ Does the request contain an explicit user-provided Scaleway IAM API key?
    │       │
    │       ├─ YES → Live API path (Tier 1 — beta)
    │       │         Log: "User-provided API key received; using live pricing. Key will not be stored."
    │       │         Call: GET https://api.scaleway.com/billing/v2beta1/products
    │       │               X-Auth-Token: <user-provided-key>
    │       │         On success  → label result live-price; include response timestamp
    │       │                       Note: endpoint is beta; stability is low-medium
    │       │         On 404/error → log status; fall through to Tier 2
    │       │         After fetch → discard key; do not retain across turns
    │       │
    │       └─ NO  → Documentation path (Tier 2)
    │                 Fetch: https://www.scaleway.com/en/pricing/  (WebFetch, no auth)
    │                 On success  → label result documentation-based
    │                 On failure  → use Tier 3 cached reference
    │
    └─ END
```

### Tier 1 — Beta Billing API

| Attribute | Value |
|-----------|-------|
| Endpoint | `https://api.scaleway.com/billing/v2beta1/products` |
| Auth header | `X-Auth-Token: <user-provided-key>` |
| Stability | Beta (low-medium); may return 404 or undocumented errors |
| Rate limit | ~60 requests/minute (per-route limits undocumented) |
| Response currency | EUR only |
| Provenance label | `live-price` |
| USD conversion | Required; use live EUR/USD rate from official-sources.md |
| Post-fetch action | Discard key; never carry across turns |

### Tier 2 — Official Pricing Page (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://www.scaleway.com/en/pricing/` |
| Auth required | No |
| Provenance label | `documentation-based` |
| Currency | EUR; convert to USD using live rate |

### Tier 3 — Cached Reference (static fallback of last resort)

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Scaleway | — |
| Instance type | PRO2-XS | Smallest production-grade instance |
| vCPU | 2 | — |
| RAM | 8 GiB | — |
| Storage | 20 GiB SSD (local) | Included in instance price |
| Region | fr-par (Paris, France) | — |
| Monthly estimate | ~€10–14/month | `documentation-based` (stale; verify before use) |
| USD note | Convert using live EUR/USD rate | See official-sources.md — Exchange Rate Sources |

---

## Alibaba Cloud

No public unauthenticated pricing API exists for Alibaba Cloud. The fallback chain starts
at Tier 2 (scrape) since Tier 1 (live authenticated API) is not usable for this skill.

### Decision tree

```
Request arrives
    │
    ├─ Tier 2a — Primary scrape
    │     Fetch: https://www.alibabacloud.com/cloud-computing/pricing  (WebFetch, no auth)
    │     HTML parser required; page contains product cards and pricing zones per region
    │     On success  → parse product pricing cards → label result documentation-based
    │     On failure (HTML structure changed, timeout, 403, 429)
    │             → fall through to Tier 2b
    │
    ├─ Tier 2b — Cost calculator fallback
    │     Fetch: https://www.alibabacloud.com/price-calculator  (WebFetch, no auth)
    │     On success  → extract visible pricing data → label result documentation-based
    │                   Include note: "Primary pricing page unavailable; estimate from calculator"
    │     On failure  → fall through to Tier 3 cached reference
    │
    ├─ Tier 3 — Cached reference (static fallback of last resort)
    │     Use cached reference data below
    │     Label: documentation-based (stale; pricing may be outdated)
    │     Include note: "All live sources unavailable; price may be stale — verify at
    │                    https://www.alibabacloud.com/cloud-computing/pricing"
    │
    └─ END
```

> **CNY note**: For mainland (`cn-*`) regions, all prices from any tier are in CNY.
> Apply CNY-to-USD conversion using a live rate with timestamp before reporting in USD.
> See [./currency-handling.md](./currency-handling.md) — CNY section for the full
> conversion procedure and mandatory timestamp fields.

### Tier 2a — Primary Pricing Page (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://www.alibabacloud.com/cloud-computing/pricing` |
| Auth required | No |
| Parser required | Yes — HTML; no JSON feed |
| Provenance label | `documentation-based` |
| Currency | CNY (mainland `cn-*` regions); USD (international regions) |
| Staleness risk | Medium — page structure may change without notice |

### Tier 2b — Cost Calculator (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://www.alibabacloud.com/price-calculator` |
| Auth required | No |
| Provenance label | `documentation-based` |
| Additional note | Include: "Primary pricing page unavailable; estimate derived from calculator page" |

### Tier 3 — Cached Reference (static fallback of last resort)

Use only when both Tier 2a and Tier 2b fetches fail.

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Alibaba Cloud | — |
| Instance type | ecs.t6-c1m1.small | Entry-level burstable instance |
| vCPU | 1 | — |
| RAM | 1 GiB | — |
| Storage | 20 GiB cloud disk | Billed separately |
| Region | cn-shanghai (Mainland China) | CNY region |
| Monthly estimate (CNY) | ~¥130 CNY/month | `documentation-based` (stale; verify before use) |
| Monthly estimate (USD) | ~$18 USD/month | Conversion requires live CNY/USD rate with timestamp |
| USD note | Convert using live CNY/USD rate | See currency-handling.md — CNY section |

> Always note in the output that this figure is a static cached reference and may not
> reflect the current price. Direct the user to
> https://www.alibabacloud.com/cloud-computing/pricing to verify.

---

## Tencent Cloud

No public unauthenticated pricing API exists for Tencent Cloud. The fallback chain starts
at Tier 2 (scrape) since Tier 1 (live authenticated API) is not usable for this skill.
JavaScript rendering may be required on the primary pricing page.

### Decision tree

```
Request arrives
    │
    ├─ Tier 2a — Primary scrape
    │     Fetch: https://cloud.tencent.com/product/cvm/pricing  (WebFetch, no auth)
    │     Note: JavaScript rendering may be required; dynamically loaded price tables
    │     On success  → parse CVM price tables → label result documentation-based
    │     On failure (JS rendering unavailable, HTML structure changed, timeout, 403, 429)
    │             → fall through to Tier 2b
    │
    ├─ Tier 2b — Cost calculator fallback
    │     Fetch: https://cloud.tencent.com/price  (WebFetch, no auth)
    │     Note: JavaScript rendering may also be required here
    │     On success  → extract visible pricing data → label result documentation-based
    │                   Include note: "Primary CVM pricing page unavailable; estimate from calculator"
    │     On failure  → fall through to Tier 3 cached reference
    │
    ├─ Tier 3 — Cached reference (static fallback of last resort)
    │     Use cached reference data below
    │     Label: documentation-based (stale; pricing may be outdated)
    │     Include note: "All live sources unavailable; price may be stale — verify at
    │                    https://cloud.tencent.com/product/cvm/pricing"
    │
    └─ END
```

> **CNY note**: For mainland (`ap-beijing`, `ap-shanghai`, `ap-guangzhou`, and other mainland)
> regions, all prices from any tier are in CNY. Apply CNY-to-USD conversion using a live rate
> with timestamp before reporting in USD. See
> [./currency-handling.md](./currency-handling.md) — CNY section for the full conversion
> procedure and mandatory timestamp fields.

### Tier 2a — Primary CVM Pricing Page (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://cloud.tencent.com/product/cvm/pricing` |
| Auth required | No |
| JS rendering | May be required to resolve dynamically loaded price tables |
| Provenance label | `documentation-based` |
| Currency | CNY (mainland regions); USD (international regions) |
| Staleness risk | Medium — page structure may change; JS rendering adds fragility |

### Tier 2b — Cost Calculator (WebFetch, no auth)

| Attribute | Value |
|-----------|-------|
| URL | `https://cloud.tencent.com/price` |
| Auth required | No |
| JS rendering | May be required |
| Provenance label | `documentation-based` |
| Additional note | Include: "Primary CVM pricing page unavailable; estimate derived from calculator page" |

### Tier 3 — Cached Reference (static fallback of last resort)

Use only when both Tier 2a and Tier 2b fetches fail.

| Field | Value | Provenance |
|-------|-------|-----------|
| Provider | Tencent Cloud | — |
| Instance type | Standard S5.LARGE8 | Standard compute instance |
| vCPU | 2 | — |
| RAM | 8 GiB | — |
| Storage | 50 GiB cloud disk | Billed separately |
| Region | ap-beijing (Beijing, Mainland China) | CNY region |
| Monthly estimate (CNY) | ~¥600 CNY/month | `documentation-based` (stale; verify before use) |
| Monthly estimate (USD) | ~$83 USD/month | Conversion requires live CNY/USD rate with timestamp |
| USD note | Convert using live CNY/USD rate | See currency-handling.md — CNY section |

> Always note in the output that this figure is a static cached reference and may not
> reflect the current price. Direct the user to
> https://cloud.tencent.com/product/cvm/pricing to verify.

---

## CNY→USD Conversion Fallback

Used whenever Alibaba Cloud (mainland `cn-*` regions) or Tencent Cloud (mainland regions)
prices are expressed in CNY and must be converted to USD for reporting.

### Decision tree

```
CNY price obtained (any tier)
    │
    ├─ Tier 1 — ExchangeRate-API (preferred, no auth)
    │     Fetch: https://v6.exchangerate-api.com/v6/latest/CNY
    │     On success  → use CNY-per-USD rate from response
    │                   record: conversion_rate, source_url, timestamp (ISO 8601)
    │     On failure  → fall through to Tier 2
    │
    ├─ Tier 2 — ECB daily feed (EUR base; cross-rate via USD)
    │     Fetch: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml
    │     Derive CNY/USD cross-rate: CNY_per_USD = (ECB CNY_per_EUR) / (ECB USD_per_EUR)
    │     On success  → use derived rate
    │                   record: conversion_rate, source_url, timestamp (ISO 8601)
    │     On failure  → fall through to Tier 3
    │
    ├─ Tier 3 — Cached rate (stale fallback of last resort)
    │     Use the most recently known CNY/USD rate from this reference file
    │     Label: assumed: 24h stale
    │     Include note: "Exchange rate could not be refreshed; rate may be stale — verify
    │                    at https://www.pbc.gov.cn/ before relying on this conversion"
    │
    └─ END
```

### Mandatory output fields for every CNY→USD conversion

| Field | Type | Example |
|-------|------|---------|
| `conversion_rate` | float (CNY per USD) | `7.25` |
| `source_url` | string | `https://v6.exchangerate-api.com/v6/latest/CNY` |
| `timestamp` | ISO 8601 | `2026-05-13T08:00:00Z` |

If the rate is from Tier 3 (stale), also include:
- `staleness_label`: `assumed: 24h stale`
- `verify_url`: `https://www.pbc.gov.cn/`

### Example labels

Tier 1 or Tier 2 (live rate):
```
[documentation-based + live-rate: 7.25 CNY/USD @ 2026-05-13T08:00:00Z via https://v6.exchangerate-api.com/v6/latest/CNY]
```

Tier 3 (stale cached rate):
```
[documentation-based + assumed: 24h stale rate 7.25 CNY/USD — verify at https://www.pbc.gov.cn/]
```

---

## Fallback Failure Handling

If all available tiers fail for any provider:

1. Return a `fetch-failed` label on the affected line item.
2. State which tiers were attempted and what errors were returned (HTTP status or timeout).
3. Include an explicit uncertainty warning:
   > "Price for {provider} {resource} could not be confirmed. Omitted from total. Retry
   > or consult {pricing-page-url} directly."
4. Do not substitute a guess or a memorized price without a label.