# Tbill yield convert

`tbill-yield-convert` · version 1.0.0 · Financial calculations · free, no key needed

Convert a Treasury bill price, discount rate, investment rate or money-market yield into all four (31 CFR 356 App. B).

**Use when you need to: treasury bill discount rate to yield · T-bill price from discount rate · bond equivalent yield of a treasury bill.**

## Decide before calling

Read the [versioned contract](/v1/tools/tbill-yield-convert/versions/1.0.0) and the supported scope below. Reuse `tbill-yield-convert@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `tbill-yield-convert@1.0.0` for treasury bill discount rate to yield. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- treasury bill discount rate to yield
- T-bill price from discount rate
- bond equivalent yield of a treasury bill
- convert bank discount rate to investment rate
- Excel TBILLEQ TBILLYIELD TBILLPRICE equivalent
- money market yield of a T-bill
- coupon equivalent yield of a bill
- what price does a 13 week bill at 5 percent discount cost
- המרת ריבית ניכיון של אג"ח אוצר קצר לתשואה

## Not supported

- coupon Treasury notes and bonds (use bond-yield-from-price)
- auction allotment, non-competitive bidding or live auction results
- business-day or holiday adjustment of settlement and maturity
- foreign bill conventions (act/365 discount markets) and tax-equivalent yield

## Behavior

- Dates are strict ISO YYYY-MM-DD real dates in years 1900 to 2200. t = days to maturity = actual days from settlement to maturity; settlement must be strictly before maturity and t must be at most 366, else invalid_input.
- Exactly one of price (per 100 of face), discount_rate, investment_rate and money_market_yield must be given (none or several is invalid_input). It is used exactly as given and echoed rounded once; the other three outputs come from the exact price. Ranges: 0 < price <= 1000, -1 <= discount_rate <= 1, -1 <= investment_rate <= 10, -1 <= money_market_yield <= 10. Rates are decimal fractions ("0.05" is 5 percent); a JSON number for a decimal field is invalid_input.
- year_basis y is 366 when a 29 February d satisfies settlement < d <= settlement + 365 days, else 365 (settlement 2024-02-29 gives 365; 2023-03-01 gives 366).
- Discount rate (360-day basis): price = 100*(1 - discount_rate*t/360) and discount_rate = ((100 - price)/100)*(360/t). Money-market yield: price = 100/(1 + money_market_yield*t/360) and money_market_yield = ((100 - price)/price)*(360/t).
- Investment rate (bond-equivalent, actual/y): when 2t <= y it is ((100 - price)/price)*(y/t) with price = 100/(1 + investment_rate*t/y) and investment_formula simple. When 2t > y, price = 100/(1 + (t/y)*i + (t/(2y) - 1/4)*i^2) with i = investment_rate, and the inverse is i = (-b + sqrt(b^2 - 4ac))/(2a) with a = t/(2y) - 1/4, b = t/y, c = (price - 100)/price (Treasury form); investment_formula is quadratic. At 2t = y the simple formula is used.
- A price implied by the input rate that is not positive (discount_rate*t/360 >= 1, or 1 + money_market_yield*t/360 <= 0) is not_computable. Excel TBILLPRICE, TBILLYIELD and TBILLEQ always use a 365-day year and a 182-day half-year cut, so year_basis 366 can differ from TBILLEQ; TBILLYIELD equals money_market_yield and TBILLEQ equals investment_rate.
- scale (0 to 12, default 6) sets the digits of price; rate_scale (0 to 12, default 10) sets the digits of the three rates; rounding is half-up (default, half away from zero), half-even, half-down, up, down, ceiling or floor, applied once to each exact value. Exact BigInt arithmetic with a correctly rounded square root; outputs never contain -0.
- Any string input over 64 UTF-8 bytes is limit_exceeded, checked before parsing; a lone surrogate is invalid_input.
- Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

## Input

- `settlement` (string, required): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `maturity` (string, required): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `price` (string, optional): max length 64; pattern `^(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$`
- `discount_rate` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$`
- `investment_rate` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$`
- `money_market_yield` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$`
- `scale` (integer, optional): min 0; max 12
- `rate_scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `price` (string, required): pattern `^(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `discount_rate` (string, required): pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `investment_rate` (string, required): pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `money_market_yield` (string, required): pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `days_to_maturity` (integer, required): min 1; max 366
- `year_basis` (one of 365, 366, required)
- `investment_formula` (one of "simple", "quadratic", required)

## Limits

- max string bytes: 64

## Example

Request input:

```json
{
  "settlement": "2008-03-31",
  "maturity": "2008-06-01",
  "discount_rate": "0.09",
  "scale": 2,
  "rate_scale": 6
}
```

Response:

```json
{
  "result": {
    "price": "98.45",
    "discount_rate": "0.090000",
    "investment_rate": "0.092687",
    "money_market_yield": "0.091417",
    "days_to_maturity": 62,
    "year_basis": 365,
    "investment_formula": "simple"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "tbill-yield-convert",
  "version": "1.0.0",
  "input": {
    "settlement": "2008-03-31",
    "maturity": "2008-06-01",
    "discount_rate": "0.09",
    "scale": 2,
    "rate_scale": 6
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/tbill-yield-convert/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"settlement":"2008-03-31","maturity":"2008-06-01","discount_rate":"0.09","scale":2,"rate_scale":6}'
```

The machine-readable contract is at [/v1/tools/tbill-yield-convert/versions/1.0.0](/v1/tools/tbill-yield-convert/versions/1.0.0).

### CLI

```sh
node cli.mjs run tbill-yield-convert 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Bond price from yield](/tools/bond-price-from-yield): Clean price, dirty price and accrued interest per 100 of a fixed-coupon bond from its yield (Excel PRICE, SIA).
- [Bond yield from price](/tools/bond-yield-from-price): Yield to maturity of a fixed-coupon bond from its clean price, with accrued and dirty price (Excel YIELD / SIA).
- [Bond duration convexity](/tools/bond-duration-convexity): Macaulay and modified duration, convexity and DV01 of a fixed-coupon bond at a yield (Excel DURATION, MDURATION).
- [Cashflow irr](/tools/cashflow-irr): IRR of equally spaced cash flows with every root reported, the chosen root named and no-solution cases signalled.
- [Cashflow npv](/tools/cashflow-npv): NPV of equally spaced cash flows, time-0 or Excel time-1, with inflow PV, outflow PV and profitability index.
- [Cashflow xnpv](/tools/cashflow-xnpv): NPV of dated cash flows with the Excel XNPV 365-day exponent and an explicit valuation date.