Merge pull request #152 from balancer/151-add-api-examples

Add API examples.

docs/data-and-analytics/data-and-analytics/balancer-api/balancer-api.md

@@ -0,0 +1,37 @@
+---
+title: Balancer API
+order: 3
+---
+# Balancer API
+Balancer's API exposes data on Balancer's smart contracts accessible via graphql. The API is running as a graphql server and is deployed at [https://api-v3.balancer.fi](https://api-v3.balancer.fi).
+
+:::info Want to keep up with changes to the API?
+You can subscribe to the [Telegram channel](https://t.me/BalBeetsApi) or check out the [repo](https://github.com/balancer/backend) stay updated. 
+:::
+
+Queries are organised around these main domains:
+
+- Pools
+- Gauges
+- Events
+- Users
+- Tokens
+- Prices
+- SOR (Smart Order Router used for swaps)
+
+One of the conventions is to use "dynamicData" for querying changing parts of the state.
+
+Further documentation is available on the self documented [api server](https://api-v3.balancer.fi).
+
+# Examples
+
+* [Pools - Get a pool's details including APRs](./pool-details-with-apr.md)
+* [Pools - Pools with TVL greater than $10k](./pools-with-tvl.md)
+* [Pools - Top 10 pools ordered by TVL](./pools-top-ordered-tvl.md)
+* [Pools - Get swap events for a pool](./pool-swap-events.md)
+* [Swap - Query the Smart Order Router (SOR)](./swap-query-sor.md)
+* [User - Get pool balances for a user](./user-pool-balance.md)
+* [User - Get pool join & exits events for a user](./user-pool-join-exits.md)
+
+
+

docs/data-and-analytics/data-and-analytics/balancer-api/pool-details-with-apr.md

@@ -0,0 +1,33 @@
+---
+title: Pools - Get details including APRs
+---
+
+# Get a pool's details including APRs
+```graphql
+{
+  poolGetPool(id: "0x7f2b3b7fbd3226c5be438cde49a519f442ca2eda00020000000000000000067d", chain:MAINNET) {
+    id
+    name
+    type
+    version
+    allTokens {
+      address
+      name
+    }
+    poolTokens {
+      address
+      symbol
+      balance
+      hasNestedPool
+    }
+    dynamicData {
+      totalLiquidity
+      aprItems {
+        title
+        type
+        apr
+      }
+    }
+  }
+}
+```

docs/data-and-analytics/data-and-analytics/balancer-api/pool-swap-events.md

@@ -0,0 +1,26 @@
+---
+title: Pools - Swap Events
+---
+
+# Get swap events for a pool
+
+As this is a CowAMM pool we also use the expanded `GqlPoolSwapEventCowAmm` type to get CowAMM specific swap data.
+
+```
+{
+  poolEvents(
+    where: {typeIn: [SWAP], chainIn: [MAINNET], poolIdIn: ["0xf08d4dea369c456d26a3168ff0024b904f2d8b91"]}
+  ) {
+    type
+    valueUSD
+    ... on GqlPoolSwapEventCowAmm {
+      surplus {
+        address
+        amount
+        valueUSD
+      }
+    }
+  }
+}
+
+```

docs/data-and-analytics/data-and-analytics/balancer-api/pools-top-ordered-tvl.md

@@ -0,0 +1,28 @@
+---
+title: Pools - Top 10 Ordered by TVL
+---
+
+# Query to find top 10 pools orderered by TVL
+
+This query also returns the pools APRs and staking gauge. One of the conventions is to use "dynamicData" for querying changing parts of the state.
+
+```graphql
+{
+  poolGetPools(first:10, orderBy:totalLiquidity) {
+    id
+    name
+    chain
+    dynamicData {
+      totalLiquidity
+      aprItems {
+        apr
+      }
+    }
+    staking {
+      gauge {
+        gaugeAddress
+      }
+    }
+  }
+}
+```

docs/data-and-analytics/data-and-analytics/balancer-api/pools-with-tvl.md

@@ -0,0 +1,15 @@
+---
+title: Pools - With TVL greater than $10k
+---
+
+# Query all pools on Arbitrum and Avalanche that have TVL greater than $10k
+
+```graphql
+{
+  poolGetPools(where: {chainIn: [AVALANCHE, ARBITRUM], minTvl: 10000}) {
+    id
+    address
+    name
+  }
+}
+```

docs/data-and-analytics/data-and-analytics/balancer-api/swap-query-sor.md

@@ -0,0 +1,26 @@
+---
+title: Swap - Query the Smart Order Router
+---
+
+# Swap - Query the Smart Order Router (SOR)
+
+In this example we query for best paths to swap 1WETH to USDC. Note the use of human scaled amount.
+
+```graphql
+{
+  sorGetSwapPaths(
+    chain: MAINNET
+    swapAmount: "1"
+    swapType: EXACT_IN
+    tokenIn: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
+    tokenOut: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+  ) {
+    swapAmountRaw
+    returnAmountRaw
+    priceImpact {
+      priceImpact
+      error
+    }
+  }
+}
+```

docs/data-and-analytics/data-and-analytics/balancer-api/user-pool-balance.md

@@ -0,0 +1,23 @@
+---
+title: User - Get pool balances
+---
+
+# Get pool balances for a user
+
+As this is a CowAMM pool we also use the expanded `GqlPoolSwapEventCowAmm` type to get CowAMM specific swap data.
+
+```
+{
+  userGetPoolBalances(
+    address: "0x..."
+    chains: [MAINNET]
+  ) {
+    totalBalance
+    walletBalance
+    stakedBalance
+    poolId
+    tokenAddress
+    tokenPrice
+  }
+}
+```

docs/data-and-analytics/data-and-analytics/balancer-api/user-pool-join-exits.md

@@ -0,0 +1,24 @@
+---
+title: User - Get joins & exit events for a pool
+---
+
+# Get pool join & exits events for a user
+
+```
+{
+  userGetPoolJoinExits(
+    poolId: "0x3de27efa2f1aa663ae5d458857e731c129069f29000200000000000000000588"
+    chain: MAINNET
+    address: "0x741AA7CFB2c7bF2A1E7D4dA2e3Df6a56cA4131F3"
+  ) {
+    type
+    tx
+    valueUSD
+    amounts {
+      address
+      amount
+    }
+  }
+}
+
+```