feat: add SBOR action provider for benchmark lending rates

typescript/.changeset/sbor-action-provider.md

@@ -0,0 +1,5 @@
+---
+"@coinbase/agentkit": minor
+---
+
+Added the SBOR action provider, a read-only benchmark of lending rates. `get_sbor_rate`, `compare_rate_to_sbor` and `list_sbor_markets` let an agent check an offered borrow or supply rate against the SBOR indices on Stacks, or against the cost of borrowing USDC against bitcoin on Base and Ethereum, before acting. It needs no key and never sends a transaction.

typescript/agentkit/README.md

@@ -555,6 +555,23 @@ const agent = createAgent({
 </table>
 </details>
 <details>
+<summary><strong>SBOR</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>get_sbor_rate</code></td>
+    <td width="768">Gets the current SBOR benchmark lending rates, read from lending contract state and published daily: the SBOR indices on Stacks, and the cost of borrowing USDC against bitcoin on Base and Ethereum.</td>
+</tr>
+<tr>
+    <td width="200"><code>compare_rate_to_sbor</code></td>
+    <td width="768">Compares an offered borrow or supply rate against an SBOR benchmark before acting, and flags a borrow more than 50 basis points above it as one to stop and ask a human about.</td>
+</tr>
+<tr>
+    <td width="200"><code>list_sbor_markets</code></td>
+    <td width="768">Lists the lending markets behind an SBOR benchmark, with each market's rates, utilization and depth.</td>
+</tr>
+</table>
+</details>
+<details>
 <summary><strong>Superfluid</strong></summary>
 <table width="100%">
 <tr>

typescript/agentkit/src/action-providers/index.ts

@@ -23,6 +23,7 @@ export * from "./pyth";
 export * from "./moonwell";
 export * from "./morpho";
 export * from "./opensea";
+export * from "./sbor";
 export * from "./spl";
 export * from "./superfluid";
 export * from "./sushi";

typescript/agentkit/src/action-providers/sbor/README.md

@@ -0,0 +1,52 @@
+# SBOR Action Provider
+
+This directory contains the SBOR action provider implementation, which lets an agent check a lending rate against the market before it borrows. [SBOR](https://sbor.xyz) publishes benchmark lending rates read from lending contract state, once a day: the SBOR indices, one borrow and one supply rate per currency on Stacks, and a reference for the cost of borrowing USDC against bitcoin on Base and Ethereum.
+
+The provider only reads SBOR's public API. It needs no key and no wallet, and never builds or sends a transaction.
+
+## Directory Structure
+
+```
+sbor/
+├── constants.ts                # API endpoint, benchmarks, thresholds
+├── index.ts                    # Main exports
+├── README.md                   # Documentation
+├── sborActionProvider.test.ts  # Tests for the provider
+├── sborActionProvider.ts       # Main provider with the SBOR actions
+├── schemas.ts                  # Action input schemas
+├── types.ts                    # Type definitions for the SBOR fixing
+└── utils.ts                    # Fetching, freshness and benchmark resolution
+```
+
+## Actions
+
+- `get_sbor_rate`: Get the current benchmark rates
+
+  - One benchmark, or all of them
+  - Returns the age of the fixing and flags data older than 48 hours as stale
+  - Lists any benchmark not published in the fixing, to be treated as unknown, never as zero
+
+- `compare_rate_to_sbor`: Compare an offered rate against a benchmark
+
+  - Returns the difference in basis points, the verdict, and the best market behind the benchmark
+  - Sets `stopAndAskHuman` when a borrow is more than 50 basis points above the benchmark
+  - Returns no verdict on data older than 48 hours, or when the benchmark is not published
+
+- `list_sbor_markets`: List the markets behind a benchmark
+
+  - Each market's borrow and supply rate, utilization and depth
+
+## Benchmarks
+
+- `SBOR-USD`, `SBOR-BTC`, `SBOR-STX`: the SBOR indices, for lending on Stacks. A dollar on Stacks is borrowed against any crypto collateral.
+- `BTC-COLLATERAL-USDC`: a reference, not an SBOR index. The cost of borrowing USDC against bitcoin wrapped by a custodian (cbBTC, WBTC), from the Morpho markets on Base and Ethereum whose only collateral is that bitcoin. Published only when every market was read.
+
+Rates are effective annual percentages (APY). Names returned by the API are sanitized before they reach the agent.
+
+## Network Support
+
+SBOR reads public data and works with any network.
+
+## Notes
+
+SBOR is independent and free to use, including commercially, with attribution. The methodology is at [sbor.xyz/llms.txt](https://sbor.xyz/llms.txt). SBOR publishes market data, not financial advice.

typescript/agentkit/src/action-providers/sbor/constants.ts

@@ -0,0 +1,37 @@
+/**
+ * Base URL of SBOR's public API. No key, no registration.
+ */
+export const SBOR_BASE_URL = "https://sbor.xyz";
+
+/**
+ * The current fixing, republished once a day.
+ */
+export const SBOR_LATEST_URL = `${SBOR_BASE_URL}/api/v1/latest.json`;
+
+/**
+ * A verdict an agent may act on must not rest on data older than this.
+ */
+export const STALE_AFTER_HOURS = 48;
+
+/**
+ * SBOR's default: stop and ask a human before borrowing more than this many
+ * basis points above the benchmark.
+ */
+export const STOP_THRESHOLD_BPS = 50;
+
+/**
+ * The SBOR indices, one per currency on Stacks.
+ */
+export const SBOR_INDICES = ["SBOR-USD", "SBOR-BTC", "SBOR-STX"] as const;
+
+/**
+ * The cost of borrowing USDC against bitcoin wrapped by a custodian (cbBTC,
+ * WBTC), from the Morpho markets on Base and Ethereum whose only collateral is
+ * that bitcoin. A reference, not an SBOR index.
+ */
+export const BTC_COLLATERAL_USDC = "BTC-COLLATERAL-USDC";
+
+/**
+ * Every benchmark an offered rate can be compared against.
+ */
+export const SBOR_BENCHMARKS = [...SBOR_INDICES, BTC_COLLATERAL_USDC] as const;

typescript/agentkit/src/action-providers/sbor/index.ts

@@ -0,0 +1 @@
+export * from "./sborActionProvider";