From efe6713d595c4667059d1427870efe55df7dc44a Mon Sep 17 00:00:00 2001
From: Ashar2shahid <31223740+Ashar2shahid@users.noreply.github.com>
Date: Wed, 16 Oct 2024 21:12:53 +0530
Subject: [PATCH] Document Signed APIs and Providers (#838)

* document signed apis

* remove yarn lock

* update header

* Update docs/reference/dapis/understand/signed-apis.md

Co-authored-by: Derek Croote <dcroote@users.noreply.github.com>

* Update docs/reference/dapis/understand/signed-apis.md

Co-authored-by: Derek Croote <dcroote@users.noreply.github.com>

* Update docs/reference/dapis/understand/signed-apis.md

Co-authored-by: Derek Croote <dcroote@users.noreply.github.com>

---------

Co-authored-by: Derek Croote <dcroote@users.noreply.github.com>
---
 docs/explore/dapis/OEV.md                     |  3 +-
 .../explore/dapis/how-are-dAPIs-maintained.md | 11 +++
 docs/explore/dapis/using-dapis.md             | 59 ------------
 docs/explore/dapis/what-are-dapis.md          |  2 +-
 docs/explore/sidebar.js                       |  4 -
 docs/reference/dapis/sidebar.js               |  4 +
 docs/reference/dapis/understand/index.md      | 12 ++-
 .../reference/dapis/understand/signed-apis.md | 94 +++++++++++++++++++
 8 files changed, 122 insertions(+), 67 deletions(-)
 delete mode 100644 docs/explore/dapis/using-dapis.md
 create mode 100644 docs/reference/dapis/understand/signed-apis.md

diff --git a/docs/explore/dapis/OEV.md b/docs/explore/dapis/OEV.md
index 4cc30629..f2643ce2 100644
--- a/docs/explore/dapis/OEV.md
+++ b/docs/explore/dapis/OEV.md
@@ -24,8 +24,7 @@ capture value that would otherwise have gone to third parties.
 Any update to data feeds, or a lack thereof, can create opportunities for OEV
 such as arbitrage and liquidations. During each of these interactions value is
 leaking from the dApp users to both searchers and blockchain validators. Learn
-more about OEV in a summary of the
-[OEV Litepaper](https://medium.com/api3/oracle-extractable-value-oev-13c1b6d53c5b).
+more about OEV [here](/reference/oev-network).
 
 ### Leveraging OEV alongside dAPIs
 
diff --git a/docs/explore/dapis/how-are-dAPIs-maintained.md b/docs/explore/dapis/how-are-dAPIs-maintained.md
index 59eef889..7d182af9 100644
--- a/docs/explore/dapis/how-are-dAPIs-maintained.md
+++ b/docs/explore/dapis/how-are-dAPIs-maintained.md
@@ -56,4 +56,15 @@ proxy address when calling the `read()` function on the proxy contract. If the
 dAPI interface has previously been imported, it abstracts away the technical
 implementation of accessing new data feeds.
 
+## Signed APIs
+
+The heart of dAPIs are the first-party data feeds, powered by the owners of the
+data themselves. These data source owners operate an Airnode - a small
+abstraction that takes their data and cryptographically signs it. The signer
+wallet never leaves the owner's control, and anyone can verify that a particular
+signed data was signed by the respective data source. Airnodes periodically push
+the signed data to Signed APIs.
+
+Read more about [Signed APIs](/reference/dapis/understand/signed-apis.md).
+
 <FlexEndTag/>
diff --git a/docs/explore/dapis/using-dapis.md b/docs/explore/dapis/using-dapis.md
deleted file mode 100644
index 553b0e35..00000000
--- a/docs/explore/dapis/using-dapis.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Using dAPIs in a dApp
-sidebarHeader: Explore
-sidebarSubHeader:
-pageHeader: Explore → dAPIs
-path: /explore/dapis/using-dapis.html
-outline: deep
-tags:
----
-
-<PageHeader/>
-
-<SearchHighlight/>
-
-<FlexStartTag/>
-
-# {{$frontmatter.title}}
-
-> <Video src="https://www.youtube.com/embed/FVI16FAJgjQ"/>
-
-As outlined on the page [What are dAPIs?](/explore/dapis/what-are-dapis.md),
-API3 has created a unified, user-friendly implementation that is designed to
-simplify the process of obtaining data feed services. The API3 Market enables
-dApp owners to connect to a decentralized API and access its data feeds.
-
-## A Next Generation Push Oracle
-
-dAPIs are sourced from multiple first-party oracles and aggregated using a
-median function. They operate using a push model with a variety of update
-specifications based on deviation thresholds. dAPIs have been designed to be
-simple to integrate, manage and change.
-
-### Accessing dAPIs
-
-dAPI are accessible through the [API3 Market](https://market.api3.org/dapis).
-The market enables developers to permissionlessly access price feeds and manage
-them once integrated. Once gas overheads required to activate a feed are
-provided, within minutes price reference data will be readable on-chain.
-
- <!-- <img src="../assets/images/Managed_dAPI_visual.png" style="width:500px"> -->
-
-It is worth noting that API3 operates all infrastructure required for data feed
-updates, there is no additional infrastructure to set up, operate and maintain
-by a dApp looking to utilize a dAPI.
-
-## API3 Market
-
-The API3 Market lists all available dAPIs. It represents a hub that allows
-developers to:
-
-- Search for available dAPIs data feeds to integrate
-- Provide gas for dAPIs to activate a decentralized oracle
-- Access the proxy address to read the value of a required data pair
-- Request new data types
-
-You can head to the [API3 Market](https://market.api3.org/dapis) to explore this
-further.
-
-<FlexEndTag/>
diff --git a/docs/explore/dapis/what-are-dapis.md b/docs/explore/dapis/what-are-dapis.md
index f7adde13..7ec8b892 100644
--- a/docs/explore/dapis/what-are-dapis.md
+++ b/docs/explore/dapis/what-are-dapis.md
@@ -71,7 +71,7 @@ code.
 
 <!--<img src="../assets/images/02-b-First_vs_Third_party_oracles-Descentralized_API_(dAPI).png" width="400"/-->
 
-### Activate and Manage dAPIs
+## API3 Market
 
 The API3 Market provides tooling for dApp owners to access decentralized price
 feeds, known as dAPIs. Use the [API3 Market](https://market.api3.org) to search
diff --git a/docs/explore/sidebar.js b/docs/explore/sidebar.js
index e7bd6e13..58bcfb4f 100644
--- a/docs/explore/sidebar.js
+++ b/docs/explore/sidebar.js
@@ -46,10 +46,6 @@ module.exports = [
     collapsed: false,
     items: [
       { text: 'What are dAPIs?', link: '/explore/dapis/what-are-dapis' },
-      {
-        text: 'Using dAPIs in DeFi',
-        link: '/explore/dapis/using-dapis',
-      },
       {
         text: 'How are dAPIs maintained on-chain',
         link: '/explore/dapis/how-are-dAPIs-maintained',
diff --git a/docs/reference/dapis/sidebar.js b/docs/reference/dapis/sidebar.js
index 11d62d20..1c35e893 100644
--- a/docs/reference/dapis/sidebar.js
+++ b/docs/reference/dapis/sidebar.js
@@ -15,6 +15,10 @@ module.exports = [
         text: 'Deviation thresholds',
         link: '/reference/dapis/understand/deviations',
       },
+      {
+        text: 'Signed APIs',
+        link: '/reference/dapis/understand/signed-apis',
+      },
       {
         text: 'Sponsor wallets',
         link: '/reference/dapis/understand/wallets',
diff --git a/docs/reference/dapis/understand/index.md b/docs/reference/dapis/understand/index.md
index 00e54211..a5147b60 100644
--- a/docs/reference/dapis/understand/index.md
+++ b/docs/reference/dapis/understand/index.md
@@ -80,9 +80,19 @@ heartbeat for each `beaconId` or `beaconSetId`.
 
 ## Providers for dAPIs
 
-Currently there are eight API providers each running an Airnode.
+Providers for blockchain data such as Liquid Staking Derivatives (LSDs) and
+Liquid Staking Tokens (LSTs):
+
+- Ankr
+- BlastAPI
+- Blocksize
+- drpc
+- Nodary
+
+Providers for cryptocurrency prices:
 
 - Coingecko
+- Coinmetrics
 - Coinpaprika
 - dxFeed
 - Finage
diff --git a/docs/reference/dapis/understand/signed-apis.md b/docs/reference/dapis/understand/signed-apis.md
new file mode 100644
index 00000000..e9adf1c7
--- /dev/null
+++ b/docs/reference/dapis/understand/signed-apis.md
@@ -0,0 +1,94 @@
+---
+title: Signed APIs
+sidebarHeader: Reference
+sidebarSubHeader: dAPIs
+pageHeader: Reference → dAPIs → Signed APIs
+path: /reference/dapis/understand/signed-apis.html
+outline: deep
+tags: signed-apis
+---
+
+<PageHeader/>
+
+# Signed APIs
+
+Signed APIs store the data pushed by Airnodes and expose them to the public via
+an API. This allows for various use cases, including powering API3 push oracles.
+
+Both the [Airnode](https://github.com/api3dao/airnode) and
+[Signed API](https://github.com/api3dao/signed-api) implementations are open
+source to increase the transparency and security of the process.
+
+### Endpoints
+
+Signed APIs are also open sourced for anyone to use. This is yet another step
+towards more decentralization, because even if API3 oracle service is down,
+anyone can use these existing Signed APIs to do the updates instead. This also
+allows MEV searchers to utilize the data to perform updates outside of the
+deviation parameters to further increase data feed currentness.
+
+API3 runs Signed APIs deployed on AWS, ensuring maximum uptime and reliability.
+The endpoint path of a Signed API has the following shape:
+
+```md
+<BASE_URL>/<ENDPOINT_NAME>/<AIRNODE_ADDRESS>
+```
+
+To break it down:
+
+1. `BASE_URL` - The base URL of the Signed API.
+2. `ENDPOINT_NAME` - The name of the endpoint. This is a human-readable name
+   that describes the data that is being served.
+3. `AIRNODE_ADDRESS` - The address of the Airnode. To see the data feed sources
+   refer to the [API3 market](https://market.api3.org).
+
+The following are the endpoints that are publicly available:
+
+1. `https://signed-api.api3.org/public/<AIRNODE_ADDRESS>` - The official API3
+   Signed APIs used by the push oracle to update the base feeds.
+
+For example, see the
+[API3 response for Nodary Airnode](https://signed-api.api3.org/public/0xc52EeA00154B4fF1EbbF8Ba39FDe37F1AC3B9Fd4).
+
+::: info Airnode Address
+
+To view the Airnode address of all the providers refer to the
+[API Integrations](https://github.com/api3dao/data-feeds/tree/main/packages/api-integrations/data/apis)
+repository.
+
+:::
+
+### Response
+
+The response of the Signed API is a JSON object with the following fields:
+
+1. `count` - The number of signed data entries.
+2. `data` - An object with the signed data entries. The keys are the beacon IDs
+   and the values are the signed data objects for the particular beacon(s).
+   Beacon Ids are
+   [derived](/reference/dapis/verify-beacon.html#verifying-beaconid) from the
+   hash of the provider's Airnode's address and its Template ID.
+
+For example:
+
+```json
+{
+  "count": 2,
+  "data": {
+    "0xcdaf3ecba9e3f1457b64b1dd33dd6dbd5d3a0d43dbcb6b94fbf755ca8a64f1c2": {
+      "airnode": "0x31C7db0e12e002E071ca0FF243ec4788a8AD189F",
+      "encodedValue": "0x0000000000000000000000000000000000000000000000000f710eec75e16680",
+      "signature": "0x5d382d6636f6b87642db580586bac7f57609f47d30e133dbb6bedede233a6d58065cb4aefbe2d2db1bd61ee9734a8671c05a5f2f79a0192ef491662ba3e390ac1c",
+      "templateId": "0x174bd80b61ec8451784391df43c8c4ffc4ae82216a65cc15107bfdf4c29f6ca1",
+      "timestamp": "1727085105"
+    },
+    "0x4048c53a7e6d4b857fb04bd4f496691e526f1de8f38880469ec834bc46021cd4": {
+      "airnode": "0x31C7db0e12e002E071ca0FF243ec4788a8AD189F",
+      "encodedValue": "0x0000000000000000000000000000000000000000000000000210a4cfc6940000",
+      "signature": "0x00b84c978f9bab8639a8931990aede93ce34b8f9564ced755499bac503a39d7e7dad882dd1be77954bbbf152b436912204a29a1260283dda863cf489f631a17b1c",
+      "templateId": "0xee8d0cab5281c59547d4ae9021121df9aec759d457c51b905296610fbef58bed",
+      "timestamp": "1727085103"
+    }
+  }
+}
+```