# BoxWood

> BoxWood is a programmatic commodity hedge-management platform. This API lets a customer read and manage their own hedge book — trades, positions, mark-to-market, compliance, scenarios, settlements, and confirmations. Every endpoint is authenticated and scoped to your organization; there is no anonymous or cross-customer data access.

BoxWood manages commodity hedges (swaps, collars, three-way collars, basis swaps) across natural gas, crude oil, NGLs, and basis. Authenticate with an API key (`Authorization: Bearer bw_...`) or OAuth; every response is limited to your own organization's data. The same surface is available three ways: a REST API, a read-only MCP server for AI agents, and an Excel add-in. The canonical product domain is `boxwoodapp.com`.

## Authentication

- [API keys](https://boxwoodapp.com/developers/api-keys): generate a Bearer key scoped to your organization and user. Pass it as `Authorization: Bearer bw_...`. Keys are revocable and IP-logged.
- [OAuth sessions](https://boxwoodapp.com/developers/sessions): device-flow OAuth used by the Excel add-in (sign in once per device).
- [OpenAPI spec](https://boxwoodapp.com/api/docs): machine-readable JSON schema for the documented endpoints below.

## Your hedge book (REST API)

All endpoints are `GET` unless noted and return only your organization's data.

- `/api/mtm`: portfolio mark-to-market (MTM) and projected cashflow (PCE), broken down by commodity, counterparty, and tenor, with weighted-average hedge prices and %PDP.
- `/api/hedge-book`: your positions grouped into seasonal / quarterly / calendar buckets, per commodity, with swap/collar split and per-period MTM. `?view=seasonal|calendar|monthly`.
- `/api/trades`: your trade blotter (filter by `status`, `product`, `counterparty`). `/api/trades/{id}` returns one trade with its monthly legs. `POST /api/trades` books a new trade.
- `/api/trades/summary`: hedged-volume summary by commodity bucket (NG outright, NG basis, NGL, oil) with daily rates.
- `/api/compliance`: coverage versus your hedge policy, per month, with failing months and the next test date.
- `/api/compliance/gap`: the per-month shortfall versus policy, with a pre-formatted RFQ email you can send counterparties.
- `/api/portfolio`: price-shift cashflow scenarios and sensitivities (`?ng_shift=`, `?cl_shift=`, `?ngl_shift=`, `?base_price=`).
- `/api/settles/expected`: expected settlement cashflows per counterparty for a delivery cycle (`?period=YYYY-MM`), with invoice-received and payment-due status.
- `/api/confirmations`: trade-confirmation status and DocuSign signing state. `POST` to upload a confirmation PDF.
- `/api/production`: your active production forecast with monthly rows by commodity and stream.
- `/api/counterparties`: your counterparties.

## AI agents (MCP server)

- [MCP server](https://boxwoodapp.com/developers/mcp): connect Claude Desktop, Cursor, or any MCP client using your API key. All tools are read-only and scoped to your organization.
- Tools: `get_portfolio_mtm`, `get_positions`, `get_working_orders`, `get_trades`, `get_trade`, `get_compliance`, `get_counterparties`, `get_production_forecast`.
- Example prompts: "What's my total mark-to-market?", "Am I in compliance on natural gas?", "Show my working orders and how far each is from filling."

## Spreadsheets & BI

- [Excel add-in](https://boxwoodapp.com/developers/excel-addin): `=BOXWOOD.*` custom functions that pull your hedge book (MTM, positions, production, compliance) into a worksheet. Sign in once via OAuth.
- [Power BI](https://boxwoodapp.com/developers/power-bi): connect Power BI to your hedge data via Web → Advanced with an API key; includes ready-to-paste recipe URLs and a scheduled-refresh guide.
- [Webhooks](https://boxwoodapp.com/developers/webhooks): subscribe to real-time events (trade booked, confirmation matched, MTM snapshot, order filled).

## Notes

- Every endpoint requires authentication and returns only your own organization's data. There is no public, anonymous, or cross-customer access.
- Prices and valuations in responses are outputs computed against your own positions and hedge policy.
- Customer success: morgan@boxwoodapp.com