---
name: givegigs-calculators
description: Discover and execute GiveGigs calculators programmatically using exact mathematical formulas and reference currency rates.
---

# Calculator Studio & Financial Formulas

Base URL: `https://givegigs.com`. Authenticate with `Authorization: Bearer givegigs-...` or `X-API-Key`. Private reads require `read` scope; calculations require `read` or `write` scope.

Web interface: `https://givegigs.com/calc`.

## Discover Calculator Schemas

```http
GET /api/ai/calc
```

Returns all 10 calculators with their ID, name, description, formula explanation, and input field definitions (keys, default values, min/max bounds, units).

### Supported Calculator IDs
1. `hourly-rate`: Target salary, annual expenses, billable hours/week, billable weeks, billable % -> Required hourly rate.
2. `project-quote`: Estimated hours, hourly rate, revision buffer %, fixed expenses -> Client quote & contingency.
3. `fee-grossup`: Desired net payout, platform fee %, fixed fee -> Target gross invoice amount.
4. `currency-convert`: Source amount, exchange rate, transfer fee % -> Converted amount & effective fee.
5. `retail-margin`: Cost of goods, target gross margin % -> Selling price & dollar markup.
6. `loan-amortization`: Principal amount, annual interest %, term in months -> Monthly payment & total interest.
7. `savings-growth`: Initial deposit, monthly contribution, annual return %, years -> Future balance & interest earned.
8. `roi-marketing`: Campaign ad spend, revenue generated -> Return on ad spend (ROAS) & Net ROI %.
9. `construction-sqft`: Length ft, width ft, material cost per sq ft, labor cost per sq ft -> Area & total job estimate.
10. `break-even`: Monthly fixed overhead, selling price per unit, variable cost per unit -> Break-even unit volume & revenue.

## Execute a Calculation

```http
POST /api/ai/calc
Content-Type: application/json
Authorization: Bearer givegigs-...

{
  "id": "hourly-rate",
  "values": {
    "salary": 85000,
    "expenses": 12000,
    "hours": 40,
    "weeks": 48,
    "billable": 70
  }
}
```

### Response
```json
{
  "id": "hourly-rate",
  "values": { "salary": 85000, "expenses": 12000, "hours": 40, "weeks": 48, "billable": 70 },
  "results": { "hourlyRate": 72.17, "annualBillableHours": 1344, "grossTarget": 97000 },
  "formula": "(salary + expenses) / (hours * weeks * (billable / 100))"
}
```

*Rules: Omitted fields fall back to site defaults. Unknown fields, negative values beyond minimums, or values causing division by zero return HTTP 400.*

## Live Currency Rates

```http
GET /api/calc/rate?from=USD&to=EUR
```
Returns live market conversion factor and timestamp. 503 indicates upstream rate provider is temporarily unreachable.

[Light Skill](https://givegigs.com/skill.md) · [Complete Reference](https://givegigs.com/skill-heavy.md)