file: ./content/index.mdx
meta: {
  "title": "Introduction",
  "description": "Connect external services to your app or agent.",
  "icon": "House"
}

Candle abstracts away the complexity of authenticating & comunicating with different third-party services. Our SDKs provide a simple interface to link accounts, read data, and perform write actions on behalf of the user.

import { Bot, Info, ZapIcon } from 'lucide-react'

<Cards>
  <Card icon={<ZapIcon />} title="Install the SDK" href="/setup/install" />

  <Card icon={<ZapIcon />} title="Link external services" href="/link-apis/link-account" />
</Cards>


file: ./content/link-apis/link-account.mdx
meta: {
  "title": "Linked Accounts",
  "description": "One user. Multiple accounts.",
  "icon": "Smartphone"
}

import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tabs } from 'radix-ui'

The Candle SDK must have an active user registered in order to perform read & write actions.

* Create a Candle user within your **sign in** & **sign up** flows
* Delete the Candle user on **sign out** & **account deletion**.

<Callout type="warn">
  Candle users are ephemeral and cannot be accessed again once deleted. Expect that your users will
  have to re-link their external service accounts if they log out & back in to your app.
</Callout>

### Usage

The Candle SDK exposes a set of APIs and parameters designed to support many common use cases.

Check out **code examples** below for your **platform of choice**—or mix and match to create your own solution.

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Show link UI flow</span>
      <span className="text-sm font-mono text-muted-foreground">
        linkAccount()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```ts title="App.tsx"
        import { Button, View } from 'react-native'
        // [!code highlight]
        import { useCandle } from 'react-native-candle'

        export default function App() {
          // [!code highlight]
          const candle = useCandle()

          return (
            <View>
              <Button
                title="Link Account"
                onPress={() => {
                   // [!code highlight:5]
                  candle.presentCandleLinkSheet({
                    onSuccess: (newLinkedAccount) => {
                      ...
                    },
                  });
                }}
              />
            </View>
          )
        }
        ```

        <Callout>
          Get started with the [Candle SDK for React Native](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="ContentView.swift"
        // [!code highlight]
        import Candle
        import SwiftUI

        struct ContentView: View {
          @State private var showLinkSheet = false

          var body: some View {
            ...
            // [!code highlight:5]
            .candleLinkSheet(
              isPresented: $showLinkSheet
            ) { newLinkedAccount in
              ...
            }
          }
        }
        ```

        <Callout>
          Get started with the [Candle SDK for iOS](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Application.kt"
        import androidx.compose.runtime.mutableStateOf
        import androidx.compose.runtime.remember
        import fi.candle.models.Models
        import fi.candle.ui.CandleLinkSheet

        val showLinkSheet = remember { mutableStateOf(false) }

        CandleLinkSheet(
          isPresented = showLinkSheet.value,
          services = listOf(Models.Service.UBER),
          onDismiss = { showLinkSheet.value = false },
          onLinkedAccount = { linkedAccount ->
            // Persist linkedAccount.linkedAccountID in your app
          },
        )
        ```

        <Callout>
          Get started with the [Candle SDK for Android](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```

        <Callout>
          Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
        </Callout>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Show link UI flow for Uber only</span>
      <span className="text-sm font-mono text-muted-foreground">
        linkAccount(services)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```ts title="App.tsx"
        import { Button, View } from 'react-native'
        // [!code highlight]
        import { useCandle } from 'react-native-candle'

        export default function App() {
          // [!code highlight]
          const candle = useCandle()

          return (
            <View>
              <Button
                title="Link Account"
                onPress={() => {
                   // [!code highlight:5]
                  candle.presentCandleLinkSheet({
                    services: ['uber'],
                    onSuccess: (newLinkedAccount) => {
                      ...
                    },
                  });
                }}
              />
            </View>
          )
        }
        ```

        <Callout>
          Get started with the [Candle SDK for React Native](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="ContentView.swift"
        // [!code highlight]
        import Candle
        import SwiftUI

        struct ContentView: View {
          @State private var showLinkSheet = false

          var body: some View {
            ...
            // [!code highlight:5]
            .candleLinkSheet(
              isPresented: $showLinkSheet,
              service: .uber,
            ) { newLinkedAccount in
              ...
            }
          }
        }
        ```

        <Callout>
          Get started with the [Candle SDK for iOS](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Application.kt"
        import androidx.compose.runtime.mutableStateOf
        import androidx.compose.runtime.remember
        import fi.candle.models.Models
        import fi.candle.ui.CandleLinkSheet

        val showLinkSheet = remember { mutableStateOf(false) }

        CandleLinkSheet(
          isPresented = showLinkSheet.value,
          services = listOf(Models.Service.UBER),
          onDismiss = { showLinkSheet.value = false },
          onLinkedAccount = { linkedAccount ->
            // Persist linkedAccount.linkedAccountID in your app
          },
        )
        ```

        <Callout>
          Get started with the [Candle SDK for Android](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```

        <Callout>
          Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
        </Callout>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get user profiles for all linked services</span>
      <span className="text-sm font-mono text-muted-foreground">
        getLinkedAccounts()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```ts title="Request"
        import { useCandle } from 'react-native-candle'

        const candle = useCandle()

        // [!code highlight]
        await candle.getLinkedAccounts()
        ```

        <Callout>
          Get started with the [Candle SDK for React Native](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="Request"
        import Candle

        // [!code highlight]
        try await Candle.Client.shared.getLinkedAccounts()
        ```

        <Callout>
          Get started with the [Candle SDK for iOS](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Request"
        import fi.candle.Candle
        import fi.candle.models.Models

        val linkedAccounts = Candle.Client.shared.getLinkedAccounts()

        val linkedAccount = Candle.Client.shared.getLinkedAccount(
          ref = Models.GetLinkedAccountRef(
            linkedAccountID = linkedAccounts.first().linkedAccountID,
          ),
        )

        Candle.Client.shared.unlinkAccount(
          ref = Models.DeleteLinkedAccountRef(
            linkedAccountID = linkedAccount.linkedAccountID,
          ),
        )
        ```

        <Callout>
          Get started with the [Candle SDK for Android](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="Request"
        // Coming Soon
        ```

        <Callout>
          Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
        </Callout>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get user's Uber profile only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getLinkedAccount(linkedAccountID)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```ts title="Request"
        import { useCandle } from 'react-native-candle'

        const candle = useCandle()

        // TIP: Store important refs for future use
        const linkedAccountRef = candle.getLinkedAccounts[0]

        // [!code highlight]
        await candle.getLinkedAccount(linkedAccountRef)
        ```

        <Callout>
          Get started with the [Candle SDK for React Native](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="Request"
        import Candle

        // TIP: Store important refs for future use
        let linkedAccountRef = try await Client.shared
          .getLinkedAccounts()[0].ref

        // [!code highlight:3]
        try await Candle.Client.shared.getLinkedAccount(
          ref: linkedAccountRef
        )
        ```

        <Callout>
          Get started with the [Candle SDK for iOS](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Request"
        import fi.candle.Candle
        import fi.candle.models.Models

        val linkedAccounts = Candle.Client.shared.getLinkedAccounts()

        val linkedAccount = Candle.Client.shared.getLinkedAccount(
          ref = Models.GetLinkedAccountRef(
            linkedAccountID = linkedAccounts.first().linkedAccountID,
          ),
        )

        Candle.Client.shared.unlinkAccount(
          ref = Models.DeleteLinkedAccountRef(
            linkedAccountID = linkedAccount.linkedAccountID,
          ),
        )
        ```

        <Callout>
          Get started with the [Candle SDK for Android](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="Request"
        // Coming Soon
        ```

        <Callout>
          Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
        </Callout>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Unlink Uber</span>
      <span className="text-sm font-mono text-muted-foreground">
        unlinkAccount(linkedAccountID)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```ts title="Request"
        import { useCandle } from 'react-native-candle'

        const candle = useCandle()

        // TIP: Store important refs for future use
        const linkedAccountRef = candle.getLinkedAccounts[0]

        // [!code highlight:3]
        await candle.unlinkAccount({
          linkedAccountID: linkedAccount.linkedAccountID
        })
        ```

        <Callout>
          Get started with the [Candle SDK for React Native](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="Request"
        import Candle

        // TIP: Store important IDs for future use
        let linkedAccountID = try await Client.shared
          .getLinkedAccounts()[0].ref

        // [!code highlight:3]
        try await Candle.Client.shared.unlinkAccount(
          ref: .init(linkedAccountID: linkedAccountID)
        )
        ```

        <Callout>
          Get started with the [Candle SDK for iOS](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Request"
        import fi.candle.Candle
        import fi.candle.models.Models

        val linkedAccounts = Candle.Client.shared.getLinkedAccounts()

        val linkedAccount = Candle.Client.shared.getLinkedAccount(
          ref = Models.GetLinkedAccountRef(
            linkedAccountID = linkedAccounts.first().linkedAccountID,
          ),
        )

        Candle.Client.shared.unlinkAccount(
          ref = Models.DeleteLinkedAccountRef(
            linkedAccountID = linkedAccount.linkedAccountID,
          ),
        )
        ```

        <Callout>
          Get started with the [Candle SDK for Android](/setup/install).
        </Callout>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="Request"
        // Coming Soon
        ```

        <Callout>
          Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
        </Callout>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>


file: ./content/read-apis/get-asset-accounts.mdx
meta: {
  "title": "Asset Accounts",
  "description": "Bank balances, investment portfolios, rideshare profiles, and more.",
  "icon": "Smartphone"
}

import { BrandIcon } from '@/app/components/brand-icon'
import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'
import { siAndroid, siApple, siFlutter, siReact } from 'simple-icons/icons'

Candle models all the user's store-of-value accounts as **asset accounts**. Accounts are denominated by **asset kind**:

| Asset Kind  | Example Accounts                                |
| ----------- | ----------------------------------------------- |
| `fiat`      | Bank accounts, credit cards, etc                |
| `stock`     | Investment portfolios, retirement accounts, etc |
| `crypto`    | Exchange portfolios, on-chain wallets, etc      |
| `transport` | Rideshare profiles, etc                         |

### Usage

The Candle SDK exposes a set of APIs and parameters designed to support many common use cases.

Check out **code examples** below for your **platform of choice**—or mix and match to create your own solution.

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get all accounts</span>
      <span className="text-sm font-mono text-muted-foreground">
        getAssetAccounts()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight]
            await candle.getAssetAccounts()
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              assetAccounts: [
                {
                  assetKind: "fiat",
                  accountKind: "individual",
                  nickname: "Apple Card",
                  currencyCode: "USD",
                  balance: -1245.06,
                  serviceAccountID: "...",
                  linkedAccountID: "...",
                  service: "apple",
                },
                {
                  assetKind: "stock",
                  accountKind: "joint",
                  nickname: "Joint Investing",
                  serviceAccountID: "...",
                  linkedAccountID: "...",
                  service: "robinhood",
                },
                {
                  assetKind: "transport",
                  accountKind: "business",
                  nickname: "Acme Inc",
                  serviceAccountID: "...",
                  linkedAccountID: "...",
                  service: "uber",
                },
              ],
              linkedAccounts: [
                {
                  service: "uber",
                  state: "active",
                  serviceUserID: "...",
                  linkedAccountID: "...",
                },
                {
                  service: "robinhood",
                  state: "active",
                  linkedAccountID: "...",
                  serviceUserID: "...",
                },
                {
                  service: "apple",
                  state: "active",
                  linkedAccountID: "...",
                  serviceUserID: "...",
                },
              ],
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight]
            try await Candle.Client.shared.getAssetAccounts()
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active
                ),
              ],
              assetAccounts: [
                .FiatAccount(.init(
                  assetKind: .fiat,
                  serviceAccountID: "...",
                  accountKind: .individual,
                  nickname: "Apple Card",
                  currencyCode: "USD",
                  balance: -1_245.06,
                  linkedAccountID: "...",
                  service: .apple,
                )),
                .MarketAccount(.init(
                  assetKind: .stock,
                  serviceAccountID: "...",
                  accountKind: .joint,
                  nickname: "Joint Investing",
                  linkedAccountID: "...",
                  service: .robinhood,
                )),
                .TransportAccount(.init(
                  assetKind: .transport,
                  serviceAccountID: "...",
                  accountKind: .business,
                  nickname: "Acme Inc",
                  linkedAccountID: "...",
                  service: .uber,
                )),
              ],
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val accounts = Candle.Client.shared.getAssetAccounts(
              query = Models.GetAssetAccountsQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val account = Candle.Client.shared.getAssetAccount(
              ref = Models.GetAssetAccountRef(
                linkedAccountID = "<LINKED_ACCOUNT_ID>",
                assetKind = Models.AssetKind.FIAT,
                serviceAccountID = "<SERVICE_ACCOUNT_ID>",
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val allAccounts: Models.AssetAccountsResponse = accounts
            val singleAccount: Models.AssetAccount = account
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get rideshare profiles only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getAssetAccounts(assetKind)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:3]
            await candle.getAssetAccounts({
              assetKind: 'transport'
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              assetAccounts: [
                {
                  assetKind: "transport",
                  accountKind: "business",
                  nickname: "Acme Inc",
                  serviceAccountID: "...",
                  linkedAccountID: "...",
                  service: "uber",
                },
              ],
              linkedAccounts: [
                {
                  service: "uber",
                  state: "active",
                  serviceUserID: "...",
                  linkedAccountID: "...",
                },
                {
                  service: "robinhood",
                  state: "active",
                  linkedAccountID: "...",
                  serviceUserID: "...",
                },
                {
                  service: "apple",
                  state: "active",
                  linkedAccountID: "...",
                  serviceUserID: "...",
                },
              ],
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:3]
            try await Candle.Client.shared.getAssetAccounts(
              query: .init(assetKind: .transport)
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active
                ),
              ],
              assetAccounts: [
                .TransportAccount(.init(
                  assetKind: .transport,
                  serviceAccountID: "...",
                  accountKind: .business,
                  nickname: "Acme Inc",
                  linkedAccountID: "...",
                  service: .uber,
                )),
              ],
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val accounts = Candle.Client.shared.getAssetAccounts(
              query = Models.GetAssetAccountsQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val account = Candle.Client.shared.getAssetAccount(
              ref = Models.GetAssetAccountRef(
                linkedAccountID = "<LINKED_ACCOUNT_ID>",
                assetKind = Models.AssetKind.FIAT,
                serviceAccountID = "<SERVICE_ACCOUNT_ID>",
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val allAccounts: Models.AssetAccountsResponse = accounts
            val singleAccount: Models.AssetAccount = account
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get Robinhood accounts only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getAssetAccounts(linkedAccountIDs)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // TIP: Store important IDs for future use
            let robinhoodIDs = (await candle.getLinkedAccounts())
              .filter(({ service }) => service == 'robinhood')
              .map(({ linkedAccountID }) => linkedAccountID)
              .join()

            // [!code highlight:3]
            await candle.getAssetAccounts({
              linkedAccountIDs: robinhoodIDs
            })
            ```

            <Callout type="warn">
              The `linkedAccountIDs` parameter must be a comma-separated list of IDs.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              assetAccounts: [
                {
                  assetKind: "stock",
                  accountKind: "joint",
                  nickname: "Joint Investing",
                  serviceAccountID: "...",
                  linkedAccountID: "...",
                  service: "robinhood",
                },
              ],
              linkedAccounts: [
                {
                  service: "robinhood",
                  state: "active",
                  linkedAccountID: "...",
                  serviceUserID: "...",
                },
              ],
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // TIP: Store important IDs for future use
            let robinhoodIDs = try await Client.shared
              .getLinkedAccounts()
              .filter { $0.service == .robinhood }
              .map { $0.linkedAccountID }
              .joined(separator: ",")

            // [!code highlight:3]
            try await Client.shared.getAssetAccounts(
              query: .init(linkedAccountIDs: robinhoodIDs)
            )
            ```

            <Callout type="warn">
              The `linkedAccountIDs` parameter must be a comma-separated list of IDs.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active
                ),
              ],
              assetAccounts: [
                .MarketAccount(.init(
                  assetKind: .stock,
                  serviceAccountID: "...",
                  accountKind: .joint,
                  nickname: "Joint Investing",
                  linkedAccountID: "...",
                  service: .robinhood,
                )),
              ],
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val accounts = Candle.Client.shared.getAssetAccounts(
              query = Models.GetAssetAccountsQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val account = Candle.Client.shared.getAssetAccount(
              ref = Models.GetAssetAccountRef(
                linkedAccountID = "<LINKED_ACCOUNT_ID>",
                assetKind = Models.AssetKind.FIAT,
                serviceAccountID = "<SERVICE_ACCOUNT_ID>",
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val allAccounts: Models.AssetAccountsResponse = accounts
            val singleAccount: Models.AssetAccount = account
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Refresh live account balance</span>
      <span className="text-sm font-mono text-muted-foreground">
        getAssetAccount(ref)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // TIP: Store important refs for future use
            const accountRef = (await candle.getAssetAccounts())
              .assetAccounts[0]

            // [!code highlight]
            await candle.getAssetAccount(accountRef)
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              assetKind: "fiat",
              accountKind: "individual",
              nickname: "Apple Card",
              currencyCode: "USD",
              balance: -1245.06,
              serviceAccountID: "...",
              linkedAccountID: "...",
              service: "apple",
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // TIP: Store important refs for future use
            let accountRef = try await Client.shared
              .getAssetAccounts()
              .assetAccounts[0]
              .ref

            // [!code highlight:3]
            try await Candle.Client.shared.getAssetAccount(
              ref: accountRef
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .FiatAccount(.init(
              assetKind: .fiat,
              serviceAccountID: "...",
              accountKind: .individual,
              nickname: "Apple Card",
              currencyCode: "USD",
              balance: -1_245.06,
              linkedAccountID: "...",
              service: .apple,
            ))
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val accounts = Candle.Client.shared.getAssetAccounts(
              query = Models.GetAssetAccountsQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val account = Candle.Client.shared.getAssetAccount(
              ref = Models.GetAssetAccountRef(
                linkedAccountID = "<LINKED_ACCOUNT_ID>",
                assetKind = Models.AssetKind.FIAT,
                serviceAccountID = "<SERVICE_ACCOUNT_ID>",
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val allAccounts: Models.AssetAccountsResponse = accounts
            val singleAccount: Models.AssetAccount = account
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>


file: ./content/read-apis/get-trades.mdx
meta: {
  "title": "Trades",
  "description": "Bank balances, investment portfolios, rideshare profiles, and more.",
  "icon": "Smartphone"
}

import { BrandIcon } from '@/app/components/brand-icon'
import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'
import { siAndroid, siApple, siFlutter, siReact } from 'simple-icons/icons'

Candle models all historical user activity as **trades**. Trades are denominated by **asset kinds**:

| Example Activity | Lost Asset Kind | Gained Asset Kind | Counterparty Kind   |
| ---------------- | --------------- | ----------------- | ------------------- |
| Bank transfers   | `fiat`          | `fiat`            | `service`           |
| Ride bookings    | `fiat`          | `transport`       | `user` or `service` |
| Flight bookings  | `fiat`          | `transport`       | `service`           |
| Sent money       | `fiat`          | `other`           | `user`              |
| Card swipes      | `fiat`          | `other`           | `merchant`          |
| Bank transfers   | `fiat`          | `fiat`            | `service`           |
| Stock purchases  | `fiat`          | `stock`           | `service`           |
| Crypto purchases | `fiat`          | `crypto`          | `service`           |
| Stock sales      | `stock`         | `fiat`            | `service`           |
| Crypto sales     | `crypto`        | `fiat`            | `service`           |
| Stock rewards    | `nothing`       | `stock`           | `service`           |
| Crypto rewards   | `nothing`       | `crypto`          | `service`           |
| Recieved money   | `other`         | `fiat`            | `user`              |

### Usage

The Candle SDK exposes a set of APIs and parameters designed to support many common use cases.

Check out **code examples** below for your **platform of choice**—or mix and match to create your own solution.

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get all activity</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight]
            await candle.getTrades()
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "uber",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "apple",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "service",
                    service: "robinhood",
                  },
                  lost: {
                    assetKind: "stock",
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: "sandbox",
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  },
                  gained: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: "robinhood",
                  },
                },
                {
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "user",
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  },
                  lost: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: "uber",
                  },
                  gained: {
                    assetKind: "transport",
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: {
                      latitude: 37.778457,
                      longitude: -122.389238,
                    },
                    originAddress: {
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    },
                    destinationCoordinates: {
                      latitude: 37.794652,
                      longitude: -122.402706,
                    },
                    destinationAddress: {
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    },
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: "uber",
                  },
                },
                {
                  dateTime: "2026-01-01T11:30:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "merchant",
                    name: "Starbucks",
                    logoURL: "https://example.com/starbucks.png",
                    location: {
                      countryCode: "US",
                      countrySubdivisionCode: "CA",
                      localityName: "San Francisco",
                    },
                  },
                  lost: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 6.99,
                    linkedAccountID: "...",
                    service: "apple",
                  },
                  gained: {
                    assetKind: "other",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight]
            try await Candle.Client.shared.getTrades()
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: .success,
                  counterparty: .ServiceCounterparty(.init(
                    kind: .service,
                    service: .robinhood,
                  )),
                  lost: .MarketTradeAsset(.init(
                    assetKind: .stock,
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: .sandbox,
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  )),
                  gained: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: .robinhood,
                  )),
                ),
                .init(
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: .success,
                  counterparty: .UserCounterparty(.init(
                    kind: .user,
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  )),
                  lost: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                  gained: .TransportAsset(.init(
                    assetKind: .transport,
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: .init(
                      latitude: 37.778457,
                      longitude: -122.389238,
                    ),
                    originAddress: .init(
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    ),
                    destinationCoordinates: .init(
                      latitude: 37.794652,
                      longitude: -122.402706,
                    ),
                    destinationAddress: .init(
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    ),
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                ),
                .init(
                  dateTime: "2026-01-01T11:30:00.000-05:00",
                  state: .success,
                  counterparty: .MerchantCounterparty(.init(
                    kind: .merchant,
                    name: "Starbucks",
                    logoURL: "https://example.com/starbucks.png",
                    location: .init(
                      countryCode: "US",
                      countrySubdivisionCode: "CA",
                      localityName: "San Francisco",
                    ),
                  )),
                  lost: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 6.99,
                    linkedAccountID: "...",
                    service: .apple,
                  )),
                  gained: .OtherAsset(.init(
                    assetKind: .other,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get ride bookings only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades(gainedAssetKind)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:3]
            await candle.getTrades({
              gainedAssetKind: 'transport'
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "uber",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "apple",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "user",
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  },
                  lost: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: "uber",
                  },
                  gained: {
                    assetKind: "transport",
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: {
                      latitude: 37.778457,
                      longitude: -122.389238,
                    },
                    originAddress: {
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    },
                    destinationCoordinates: {
                      latitude: 37.794652,
                      longitude: -122.402706,
                    },
                    destinationAddress: {
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    },
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: "uber",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:3]
            try await Candle.Client.shared.getTrades(
              query: .init(gainedAssetKind: .transport)
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: .success,
                  counterparty: .UserCounterparty(.init(
                    kind: .user,
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  )),
                  lost: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                  gained: .TransportAsset(.init(
                    assetKind: .transport,
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: .init(
                      latitude: 37.778457,
                      longitude: -122.389238,
                    ),
                    originAddress: .init(
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    ),
                    destinationCoordinates: .init(
                      latitude: 37.794652,
                      longitude: -122.402706,
                    ),
                    destinationAddress: .init(
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    ),
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get stock sales only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades(lostAssetKind)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:3]
            await candle.getTrades({
              lostAssetKind: 'stock'
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "uber",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "apple",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "service",
                    service: "robinhood",
                  },
                  lost: {
                    assetKind: "stock",
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: "sandbox",
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  },
                  gained: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: "robinhood",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:3]
            try await Candle.Client.shared.getTrades(
              query: .init(lostAssetKind: .stock)
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: .success,
                  counterparty: .ServiceCounterparty(.init(
                    kind: .service,
                    service: .robinhood,
                  )),
                  lost: .MarketTradeAsset(.init(
                    assetKind: .stock,
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: .sandbox,
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  )),
                  gained: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: .robinhood,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get card swipes only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades(counterpartyKind)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:3]
            await candle.getTrades({
              counterpartyKind: 'merchant'
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "uber",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "apple",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T11:30:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "merchant",
                    name: "Starbucks",
                    logoURL: "https://example.com/starbucks.png",
                    location: {
                      countryCode: "US",
                      countrySubdivisionCode: "CA",
                      localityName: "San Francisco",
                    },
                  },
                  lost: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 6.99,
                    linkedAccountID: "...",
                    service: "apple",
                  },
                  gained: {
                    assetKind: "other",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:3]
            try await Candle.Client.shared.getTrades(
              query: .init(counterpartyKind: .merchant)
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T11:30:00.000-05:00",
                  state: .success,
                  counterparty: .MerchantCounterparty(.init(
                    kind: .merchant,
                    name: "Starbucks",
                    logoURL: "https://example.com/starbucks.png",
                    location: .init(
                      countryCode: "US",
                      countrySubdivisionCode: "CA",
                      localityName: "San Francisco",
                    ),
                  )),
                  lost: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 6.99,
                    linkedAccountID: "...",
                    service: .apple,
                  )),
                  gained: .OtherAsset(.init(
                    assetKind: .other,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get last week's activity only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades(dateTimeSpan)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:3]
            await candle.getTrades({
              dateTimeSpan: 'P1W'
            })
            ```

            <Callout type="warn">
              The `dateTimeSpan` parameter must be a valid [ISO 8601 duration string.](https://en.wikipedia.org/wiki/ISO_8601#Durations)
            </Callout>

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "uber",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
                {
                  linkedAccountID: "...",
                  service: "apple",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "service",
                    service: "robinhood",
                  },
                  lost: {
                    assetKind: "stock",
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: "sandbox",
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  },
                  gained: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: "robinhood",
                  },
                },
                {
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "user",
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  },
                  lost: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: "uber",
                  },
                  gained: {
                    assetKind: "transport",
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: {
                      latitude: 37.778457,
                      longitude: -122.389238,
                    },
                    originAddress: {
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    },
                    destinationCoordinates: {
                      latitude: 37.794652,
                      longitude: -122.402706,
                    },
                    destinationAddress: {
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    },
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: "uber",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:3]
            try await Candle.Client.shared.getTrades(
              query: .init(dateTimeSpan: "P1W")
            )
            ```

            <Callout type="warn">
              The `dateTimeSpan` parameter must be a valid [ISO 8601 duration string.](https://en.wikipedia.org/wiki/ISO_8601#Durations)
            </Callout>

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .uber,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
                .init(
                  linkedAccountID: "...",
                  service: .apple,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: .success,
                  counterparty: .ServiceCounterparty(.init(
                    kind: .service,
                    service: .robinhood,
                  )),
                  lost: .MarketTradeAsset(.init(
                    assetKind: .stock,
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: .sandbox,
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  )),
                  gained: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: .robinhood,
                  )),
                ),
                .init(
                  dateTime: "2026-01-01T12:00:00.000-05:00",
                  state: .success,
                  counterparty: .UserCounterparty(.init(
                    kind: .user,
                    legalName: "John Doe",
                    avatarURL: "https://example.com/johndoe.png",
                    username: "jdoe",
                  )),
                  lost: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 22.05,
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                  gained: .TransportAsset(.init(
                    assetKind: .transport,
                    serviceTradeID: "...",
                    serviceAssetID: "...",
                    serviceAccountID: "...",
                    name: "UberXL",
                    description: "Honda Civic",
                    imageURL: "https://example.com/uberxl.png",
                    originCoordinates: .init(
                      latitude: 37.778457,
                      longitude: -122.389238,
                    ),
                    originAddress: .init(
                      value: "565 Clay St, San Francisco, CA 94111, United States",
                    ),
                    destinationCoordinates: .init(
                      latitude: 37.794652,
                      longitude: -122.402706,
                    ),
                    destinationAddress: .init(
                      value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                    ),
                    seats: 6,
                    departureDateTime: "2026-01-01T12:05:00.000-05:00",
                    arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                    linkedAccountID: "...",
                    service: .uber,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get Robinhood activity only</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrades(linkedAccountIDs)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // TIP: Store important IDs for future use
            let robinhoodIDs = (await candle.getLinkedAccounts())
              .filter(({ service }) => service == 'robinhood')
              .map(({ linkedAccountID }) => linkedAccountID)
              .join()

            // [!code highlight:3]
            await candle.getTrades({
              linkedAccountIDs: robinhoodIDs
            })
            ```

            <Callout type="warn">
              The `linkedAccountIDs` parameter must be a comma-separated list of IDs.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              linkedAccounts: [
                {
                  linkedAccountID: "...",
                  service: "robinhood",
                  serviceUserID: "...",
                  state: "active",
                },
              ],
              trades: [
                {
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: "success",
                  counterparty: {
                    kind: "service",
                    service: "robinhood",
                  },
                  lost: {
                    assetKind: "stock",
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: "sandbox",
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  },
                  gained: {
                    assetKind: "fiat",
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: "robinhood",
                  },
                },
              ]
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // TIP: Store important IDs for future use
            let robinhoodIDs = try await Client.shared
              .getLinkedAccounts()
              .filter { $0.service == .robinhood }
              .map { $0.linkedAccountID }
              .joined(separator: ",")

            // [!code highlight:3]
            try await Client.shared.getTrades(
              query: .init(linkedAccountIDs: robinhoodIDs)
            )
            ```

            <Callout type="warn">
              The `linkedAccountIDs` parameter must be a comma-separated list of IDs.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              linkedAccounts: [
                .init(
                  linkedAccountID: "...",
                  service: .robinhood,
                  serviceUserID: "...",
                  state: .active,
                ),
              ],
              trades: [
                .init(
                  dateTime: "2026-01-01T12:10:00.000-05:00",
                  state: .success,
                  counterparty: .ServiceCounterparty(.init(
                    kind: .service,
                    service: .robinhood,
                  )),
                  lost: .MarketTradeAsset(.init(
                    assetKind: .stock,
                    serviceAccountID: "...",
                    serviceAssetID: "...",
                    symbol: "AAPL",
                    amount: 1.856,
                    serviceTradeID: "...",
                    linkedAccountID: "...",
                    service: .sandbox,
                    name: "Apple",
                    color: "#000000",
                    logoURL: "https://example.com/aapl.png",
                  )),
                  gained: .FiatAsset(.init(
                    assetKind: .fiat,
                    serviceAccountID: "...",
                    currencyCode: "USD",
                    amount: 500,
                    linkedAccountID: "...",
                    service: .robinhood,
                  )),
                ),
              ]
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Get live ride status</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTrade(ref)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // TIP: Store important refs for future use
            const tradeRef = (await candle.getTrades())
              .trades[0]

            // [!code highlight]
            await candle.getTrade(tradeRef)
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            {
              dateTime: "2026-01-01T12:00:00.000-05:00",
              state: "inProgress",
              counterparty: {
                kind: "user",
                legalName: "John Doe",
                avatarURL: "https://example.com/johndoe.png",
                username: "jdoe",
              },
              lost: {
                assetKind: "fiat",
                serviceAccountID: "...",
                currencyCode: "USD",
                amount: 22.05,
                linkedAccountID: "...",
                service: "uber",
              },
              gained: {
                assetKind: "transport",
                serviceTradeID: "...",
                serviceAssetID: "...",
                serviceAccountID: "...",
                name: "UberXL",
                description: "Honda Civic",
                imageURL: "https://example.com/uberxl.png",
                originCoordinates: {
                  latitude: 37.778457,
                  longitude: -122.389238,
                },
                originAddress: {
                  value: "565 Clay St, San Francisco, CA 94111, United States",
                },
                destinationCoordinates: {
                  latitude: 37.794652,
                  longitude: -122.402706,
                },
                destinationAddress: {
                  value: "24 Willie Mays Plaza, San Francisco, CA 94107, United States",
                },
                seats: 6,
                departureDateTime: "2026-01-01T12:05:00.000-05:00",
                arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                linkedAccountID: "...",
                service: "uber",
              },
            }
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // TIP: Store important refs for future use
            let tradeRef = try await Client.shared
              .getTrades()
              .trades[0]
              .ref

            // [!code highlight:3]
            try await Candle.Client.shared.getTrade(
              ref: tradeRef
            )
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            .init(
              dateTime: "2026-01-01T12:00:00.000-05:00",
              state: .inProgress,
              counterparty: .UserCounterparty(.init(
                kind: .user,
                legalName: "John Doe",
                avatarURL: "https://example.com/johndoe.png",
                username: "jdoe",
              )),
              lost: .FiatAsset(.init(
                assetKind: .fiat,
                serviceAccountID: "...",
                currencyCode: "USD",
                amount: 22.05,
                linkedAccountID: "...",
                service: .uber,
              )),
              gained: .TransportAsset(.init(
                assetKind: .transport,
                serviceTradeID: "...",
                serviceAssetID: "...",
                serviceAccountID: "...",
                name: "UberXL",
                description: "Honda Civic",
                imageURL: "https://example.com/uberxl.png",
                originCoordinates: .init(
                  latitude: 37.778457,
                  longitude: -122.389238,
                ),
                originAddress: .init(
                  value: "565 Clay St, San Francisco, CA 94111, UniteStates",
                ),
                destinationCoordinates: .init(
                  latitude: 37.794652,
                  longitude: -122.402706,
                ),
                destinationAddress: .init(
                  value: "24 Willie Mays Plaza, San Francisco, CA 94107United States",
                ),
                seats: 6,
                departureDateTime: "2026-01-01T12:05:00.000-05:00",
                arrivalDateTime: "2026-09-14T12:15:00.000-05:00",
                linkedAccountID: "...",
                service: .uber,
              )),
            )
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val trades = Candle.Client.shared.getTrades(
              query = Models.GetTradesQuery(
                linkedAccountIDs = listOf("<LINKED_ACCOUNT_ID>"),
              ),
            )

            val trade = Candle.Client.shared.getTrade(
              ref = Models.TradeRef(id = "<TRADE_ID>"),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val tradesResponse: Models.TradesResponse = trades
            val tradeResponse: Models.Trade = trade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>


file: ./content/setup/create-user.mdx
meta: {
  "title": "Hosted Auth",
  "description": "Sign users in with a hosted Candle account grant.",
  "icon": "Smartphone"
}

import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'

Candle users should sign in through [Hosted Auth](/setup/hosted-auth). Hosted auth creates or finds
the global Candle account, unlocks the user's privacy material on `candle.fi`, asks the user to
approve your app, and returns an app-scoped grant to the SDK.

<Callout type="warn">
  The old app-scoped `createUser` flow is legacy-only. Do not use it from public native, React
  Native, Android, or web clients.
</Callout>

### Usage

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Start hosted sign in</span>
      <span className="text-sm font-mono text-muted-foreground">
        makeHostedAuthorizationRequest()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-4 md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```tsx title="UserAuthentication.tsx"
        import { useCandle } from "react-native-candle";

        export default function UserAuthentication() {
          const candle = useCandle();

          async function signIn() {
            const request = candle.makeHostedAuthorizationRequest({
              redirectUri: "my-app://oauth/callback",
            });
            // Open request.url in the system browser.
          }

          return <... />;
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="UserAuthentication.swift"
        import Candle
        import SwiftUI

        struct UserAuthentication: View {
          var body: some View { ... }

          func signIn() async throws {
            let request = try Candle.Client.shared.makeHostedAuthorizationRequest(
              redirectURI: "my-app://oauth/callback"
            )
            // Open request.url in ASWebAuthenticationSession.
          }
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="UserAuthentication.kt"
        import fi.candle.Candle

        suspend fun signIn() {
          val request = Candle.Client.shared.makeHostedAuthorizationRequest(
            redirectUri = "my-app://oauth/callback",
          )
          // Open request.url in a browser custom tab.
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Handle sign out</span>
      <span className="text-sm font-mono text-muted-foreground">
        signOut()
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-4 md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```tsx title="UserProfile.tsx"
        import { useCandle } from "react-native-candle";

        export default function UserProfile() {
          const candle = useCandle();

          async function signOut() {
            await candle.signOut();
          }

          return <... />;
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="UserProfile.swift"
        import Candle

        func signOut() async throws {
          try await Candle.Client.shared.signOut()
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="UserProfile.kt"
        import fi.candle.Candle

        suspend fun signOut() {
          Candle.Client.shared.signOut()
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>


file: ./content/setup/hosted-auth.mdx
meta: {
  "title": "Hosted Auth",
  "description": "Use Candle account auth from your app.",
  "icon": "KeyRound"
}

Hosted auth is the recommended way to let end users sign in to Candle from your app. Your app opens
the Candle web flow, Candle handles Sign in with Apple and passkey unlock on `candle.fi`, and the SDK
receives an app-scoped grant package for API calls.

### Flow

1. Register your app as a public OAuth client in the Candle dashboard.
2. Add your redirect URI or universal/app link callback to the Candle app settings.
3. Launch hosted auth with PKCE from your app.
4. Candle signs the user in, asks for consent, unlocks the user's passkey-backed privacy material,
   and returns an app grant to your callback.
5. Store the returned grant package in secure storage and use it for Candle API calls.

<Callout type="warn">
  Native/mobile clients must not embed a client secret. Use the app's client ID and PKCE for hosted
  auth. Client secrets are only for server-side customer operations.
</Callout>

<Callout type="info">
  Redirect URIs are enforced exactly. Add every callback your beta app uses, including custom
  schemes such as `myapp://candle-auth`, Android app links, iOS universal links, and local
  development callbacks.
</Callout>

### SDK Usage

The SDK can generate the PKCE verifier and encrypted grant-package key for you, then finish the
callback by exchanging the OAuth code and storing the app-scoped grant package.

```tsx title="React Native"
const request = candle.makeHostedAuthorizationRequest({
  redirectUri: 'myapp://candle-auth',
})

await openURL(request.url)

// In your deep-link handler:
await candle.completeHostedAuthorization(callbackUrl)
```

```swift title="Swift"
let request = try Candle.Client.shared.makeHostedAuthorizationRequest(
  redirectURI: "myapp://candle-auth"
)

openURL(request.url)

// In your callback handler:
try await Candle.Client.shared.completeHostedAuthorization(request: request, callbackURL: url)
```

```kotlin title="Kotlin"
val request = Candle.Client.shared.makeHostedAuthorizationRequest(
  redirectUri = "myapp://candle-auth",
)

startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(request.url)))

// In your callback handler:
Candle.Client.shared.completeHostedAuthorization(request, callbackUrl)
```

### iOS Entitlements

Hosted auth does not require the host app to enable Candle-managed Sign in with Apple or passkey
capabilities. Passkeys are created and unlocked on `candle.fi` in the browser, so customer apps do
not need to be added to Candle's AASA file. Your app only needs whatever callback registration its
own redirect URI uses, such as a custom URL scheme or its own universal link domain.

### User Identity

Candle accounts are global across customer apps. The hosted web flow verifies Apple tokens against
Candle's web Services ID, then authorizes each customer app through an app grant. Passkeys use a
Candle-generated opaque WebAuthn user handle, not your client ID, bundle ID, or the Apple `sub`.

### Billing Portal

Users can manage their individual Candle plan at `/account`. The account portal uses the same hosted
Apple identity and `candle.fi` passkey flow, then opens Stripe checkout or the Stripe billing portal
for Plus and Pro plans.


file: ./content/setup/initialize.mdx
meta: {
  "title": "Initialize",
  "description": "Get set up on app launch.",
  "icon": "Smartphone"
}

import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'

The Candle SDK must be initialized when your app or extension launches. Public clients initialize
with a client ID only, then use [Hosted Auth](/setup/hosted-auth) to receive an app-scoped grant.

<Callout type="warn">
  Do not embed a client secret in native, React Native, Android, or other public clients. Client
  secrets are only for trusted server/admin operations.
</Callout>

### Usage

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Initialize Candle in your app</span>
      <span className="text-sm font-mono text-muted-foreground">
        initialize(clientID)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-4 md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```tsx title="_layout.tsx"
        import { CandleProvider } from "react-native-candle";

        export default function RootLayout() {
          return (
            <CandleProvider clientID={'<YOUR CLIENT ID>'}>
              ...
            </CandleProvider>
          );
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="MyApp.swift"
        import Candle
        import SwiftUI

        @main struct MyApp: App {
          var body: some Scene { WindowGroup { ... } }

          init() {
            try! Candle.Client.initialize(clientID: "<YOUR CLIENT ID>")
          }
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Application.kt"
        import android.app.Application
        import fi.candle.Candle

        class MyApplication : Application() {
          override fun onCreate() {
            super.onCreate()
            Candle.Client.initialize(
              context = this,
              clientID = "<YOUR CLIENT ID>",
            )
          }
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Initialize Candle in your widget or live activity</span>
      <span className="text-sm font-mono text-muted-foreground">
        initialize(clientID, accessGroup)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-4 md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```tsx title="_layout.tsx"
        import { CandleProvider } from "react-native-candle";

        export default function RootLayout() {
          return (
            <CandleProvider clientID={'<YOUR CLIENT ID>'} accessGroup={'<YOUR ACCESS GROUP>'}>
              ...
            </CandleProvider>
          );
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```swift title="MyWidget.swift"
        import Candle
        import WidgetKit

        @main struct MyWidget: Widget {
          var body: some Widget { StaticConfiguration(...) { ... } }

          init() {
            try! Candle.Client.initialize(
              clientID: "<YOUR CLIENT ID>",
              accessGroup: "<YOUR ACCESS GROUP>"
            )
          }
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```kotlin title="Application.kt"
        import android.app.Application
        import fi.candle.Candle

        class MyApplication : Application() {
          override fun onCreate() {
            super.onCreate()
            Candle.Client.initialize(
              context = this,
              clientID = "<YOUR CLIENT ID>",
            )
          }
        }
        ```
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        ```dart title="main.dart"
        // Coming Soon
        ```
      </Tabs.Content>
    </PlatformTabsRoot>

    <Callout type="warn">
      The `accessGroup` parameter must be a valid iOS app group container ID or keychain access
      group name. Pass the same access group in each app or extension that shares Candle user data.
    </Callout>
  </Accordion>
</Accordions>


file: ./content/setup/install.mdx
meta: {
  "title": "Install",
  "description": "Use Candle in your project.",
  "icon": "Smartphone"
}

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Candle's SDKs are designed to be embedded directly into your app or agent. Install the Candle SDK for your platform of choice to get started.

<Callout>
  For production user login, use [Hosted Auth](/setup/hosted-auth). Hosted auth uses public-client
  PKCE and keeps passkeys on `candle.fi`, so customer apps do not need Candle-managed AASA entries.
</Callout>

<Accordions>
  <Accordion title="Install Candle in a React Native project">
    <Callout type="warn">
      The Candle SDK supports **iOS 17+**. If your project requires earlier version support, please
      reach out to us on [Discord](https://discord.gg/H7jQyjz7s4).
    </Callout>

    <Tabs groupId="react-native-install" items={["Expo", "Bare RN"]} persist updateAnchor>
      <Tab value="Expo">
        <Steps>
          <Step>
            Install the Candle SDK and Expo build-properties plugin.

            ```package-install
            npm install react-native-candle expo-build-properties
            ```

            <Callout type="warn">
              The `react-native-candle` package defines `peerDependencies`. If your package manager
              does not automatically install peer dependencies, please install
              `react-native-nitro-modules` explicitly.
            </Callout>

            <Callout type="info">
              Hosted Candle auth does not require your iOS app to enable Candle Sign in with Apple
              or Candle passkey Associated Domains. Register only your own redirect callback, such
              as a custom scheme or universal link.
            </Callout>
          </Step>

          <Step>
            Add `expo-build-properties` to your Expo `plugins` array and set the iOS deployment
            target to `17.0` or higher.

            ```json title="app.json"
            {
              "expo": {
                "plugins": [
                  [
                    "expo-build-properties",
                    {
                      "ios": {
                        "deploymentTarget": "17.0"
                      }
                    }
                  ]
                ]
              }
            }
            ```
          </Step>

          <Step>
            Regenerate the native project and install CocoaPods.

            ```bash
            npx expo prebuild --platform ios
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab value="Bare RN">
        <Steps>
          <Step>
            Install the Candle SDK.

            ```package-install
            npm install react-native-candle
            ```

            <Callout type="warn">
              The `react-native-candle` package defines `peerDependencies`. If your package manager
              does not automatically install peer dependencies, please install
              `react-native-nitro-modules` explicitly.
            </Callout>
          </Step>

          <Step>
            Set your app's minimum iOS deployment target to `17.0` or higher in Xcode/CocoaPods.
          </Step>

          <Step>
            Install iOS dependencies.

            ```bash
            cd ios && pod install
            ```
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Install Candle in a native iOS project">
    <Callout type="warn">
      The Candle SDK supports **iOS 17+** and **Swift 6.2+**. If your project requires earlier version
      support, please reach out to us on [Discord](https://discord.gg/H7jQyjz7s4).
    </Callout>

    <Tabs groupId="package-manager" items={["SPM", "Xcode", "CocoaPods"]} persist updateAnchor>
      <Tab value="SPM">
        Add the following lines to your `Package.swift`.

        ```swift title="Package.swift"
        let package = Package(
            dependencies: [
                // [!code highlight]
                .package(url: "https://github.com/candlefinance/candle-swift.git", from: "11.0.0"),
            ],
            targets: [
                .target(
                    dependencies: [
                        // [!code highlight]
                        .product(name: "Candle", package: "candle-swift"),
                    ]
                ),
            ]
        )

        ```
      </Tab>

      <Tab value="Xcode">
        <Steps>
          <Step>Navigate to ***File*** > ***Add Package Dependencies***.</Step>

          <Step>
            In the ***Search or enter Package URL*** field, enter:

            ```

            https://github.com/candlefinance/candle-swift

            ```
          </Step>

          <Step>
            In the ***Dependency Rule*** dropdown, make sure `Up To Next Major Version` is selected and the initial version is set to `11.0.0`.
          </Step>

          <Step>Click the ***Add Package*** button.</Step>
        </Steps>
      </Tab>

      <Tab value="CocoaPods">
        Add the following line to your `Podfile`.

        ```ruby title="Podfile"
        target 'MyApp' do
          # [!code highlight]
          pod 'Candle', '11.0.0'
        end
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Install Candle in a native Android project">
    <Tabs items={['Kotlin DSL', 'Groovy']}>
      <Tab value="Kotlin DSL">
        Add the Candle Maven registry and dependency:

        ```kotlin title="settings.gradle.kts"
        dependencyResolutionManagement {
            repositories {
                google()
                mavenCentral()
                maven {
                    url = uri("https://maven.pkg.github.com/candlefinance/candle")
                    credentials {
                        username = providers.gradleProperty("gpr.user").orNull
                            ?: System.getenv("GITHUB_ACTOR")
                        password = providers.gradleProperty("gpr.key").orNull
                            ?: System.getenv("GITHUB_TOKEN")
                    }
                }
            }
        }
        ```

        ```kotlin title="app/build.gradle.kts"
        dependencies {
            implementation("fi.candle:sdk-kotlin:11.0.0")
        }
        ```
      </Tab>

      <Tab value="Groovy">
        Add the Candle Maven registry and dependency:

        ```groovy title="settings.gradle"
        dependencyResolutionManagement {
            repositories {
                google()
                mavenCentral()
                maven {
                    url = uri("https://maven.pkg.github.com/candlefinance/candle")
                    credentials {
                        username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
                        password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GITHUB_TOKEN")
                    }
                }
            }
        }
        ```

        ```groovy title="app/build.gradle"
        dependencies {
            implementation "fi.candle:sdk-kotlin:11.0.0"
        }
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      Use a GitHub token with package read access for `maven.pkg.github.com/candlefinance/candle`.
    </Callout>
  </Accordion>

  <Accordion title="Install Candle in a Flutter project">
    <Callout>Candle for Flutter is coming soon! Get early access by reaching out to us on [Discord](https://discord.gg/H7jQyjz7s4).</Callout>
  </Accordion>

  <Accordion title="Install Candle in a web project">
    <Callout>Candle for web is coming soon! Get early access by reaching out to us on [Discord](https://discord.gg/H7jQyjz7s4).</Callout>
  </Accordion>
</Accordions>


file: ./content/write-apis/execute-trade.mdx
meta: {
  "title": "Execute Trade",
  "description": "Select a trade quote.",
  "icon": "Smartphone"
}

import { BrandIcon } from '@/app/components/brand-icon'
import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'
import { siAndroid, siApple, siFlutter, siReact } from 'simple-icons/icons'

Once you have received trade quotes and selected one, the final step is taking an action on behalf of your users.

### Usage

The Candle SDK exposes a set of APIs and parameters designed to support many common use cases.

Check out **code examples** below for your **platform of choice**—or mix and match to create your own solution.

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Execute Trade Quote</span>
      <span className="text-sm font-mono text-muted-foreground">
        executeTrade(context)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="App.tsx"
            import { Button, View } from 'react-native'
            // [!code highlight]
            import { useCandle } from 'react-native-candle'

            export default function App() {
              // [!code highlight]
              const candle = useCandle()

              return (
                <View>
                  <Button
                    title="Execute Trade"
                    onPress={() => {
                       // [!code highlight:12]
                      candle.presentCandleTradeExecutionSheet({
                        tradeQuote,
                        completion: (result) => {
                          switch result.kind {
                            case 'success':
                              const newExecutedTrade = result.value
                              ...
                            case 'error':
                              throw Error(result.error)
                          }
                        },
                      });
                    }}
                  />
                </View>
              )
            }
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            // [!code highlight]
            import Candle
            import SwiftUI

            struct TradeView: View {
              @State private var selectedTradeQuote: Candle.Models.TradeQuote? = nil

              var body: some View {
                ...
                // [!code highlight:4]
                .candleTradeExecutionSheet(item: $selectedTradeQuote) { result in
                  let newExecutedTrade = try result.get()
                  ...
                }
              }
            }
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val tradeQuote = Models.TradeQuote(
              context = "book ride",
              linkedAccountID = "<LINKED_ACCOUNT_ID>",
              lost = Models.FiatAsset(
                linkedAccountID = "<LINKED_ACCOUNT_ID>",
                serviceAccountID = "<SERVICE_ACCOUNT_ID>",
                amount = 25.0,
                currencyCode = "USD",
              ),
              gained = Models.OtherAsset(),
              counterparty = Models.ServiceCounterparty(
                service = Models.Service.UBER,
              ),
            )
            val executedTrade = Candle.Client.shared.executeTrade(
              quote = tradeQuote,
              consentToken = null,
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val trade: Models.Trade = executedTrade
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>


file: ./content/write-apis/get-trade-quotes.mdx
meta: {
  "title": "Get Trade Quotes",
  "description": "Send money, trade crypto, book rides",
  "icon": "Smartphone"
}

import { BrandIcon } from '@/app/components/brand-icon'
import { PlatformTabs, PlatformTabsRoot } from '@/app/components/platform-tabs'
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
import { Tabs } from 'radix-ui'
import { siAndroid, siApple, siFlutter, siReact } from 'simple-icons/icons'

Retrieving trade quotes is the first step of taking an action on behalf of your users—such as booking rides or trading stocks/crypto.

Each trade quote represents a possible action you can take. Once you select an action, you can execute it.

### Usage

The Candle SDK exposes a set of APIs and parameters designed to support many common use cases.

Check out **code examples** below for your **platform of choice**—or mix and match to create your own solution.

<Accordions>
  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Send $25 to @JohnDoe</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTradeQuotes(other, fiat, user)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-  md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:13]
            await candle.getTradeQuotes({
              gained: {
                assetKind: 'other',
              },
              lost: {
                assetKind: 'fiat',
                amount: 25,
              },
              counterparty: {
                kind: 'user',
                username: 'JohnDoe',
              },
            })
            ```

            <Callout type="warn">
              The `counterparty.username` field must be set to a complete, existing username. Do not include service-wide prefixes such as `@` or `$`.

              If you don't know the username of the receiving party, set the `counterparty.legalName` field instead to find matching users using a fuzzy search.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:13]
            try await Candle.Client.shared.getTradeQuotes(.init(
              gained: .OtherAsset(.init(
                assetKind: .other,
              )),
              lost: .FiatAsset(.init(
                assetKind: .fiat,
                amount: 25,
              )),
              counterparty: .UserCounterparty(.init(
                kind: .user,
                username: "JohnDoe",
              )),
            })
            ```

            <Callout type="warn">
              The `counterparty.username` field must be set to a complete, existing username. Do not include service-wide prefixes such as `@` or `$`.

              If you don't know the username of the receiving party, set the `counterparty.legalName` field instead to find matching users using a fuzzy search.
            </Callout>

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val quotes = Candle.Client.shared.getTradeQuotes(
              request = Models.TradeQuotesRequest(
                gained = Models.OtherAssetQuoteRequest(),
                lost = Models.FiatAssetQuoteRequest(
                  amount = 25.0,
                  currencyCode = "USD",
                ),
                counterparty = Models.ServiceCounterpartyQuoteRequest(
                  service = Models.Service.UBER,
                ),
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val quoteResponse: Models.TradeQuotesResponse = quotes
            val bestQuote: Models.TradeQuote? = quoteResponse.tradeQuotes.firstOrNull()
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Book Uber ride</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTradeQuotes(transport, fiat)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:16]
            await candle.getTradeQuotes({
              gained: {
                assetKind: 'transport',
                originCoordinates: {
                  latitude: 37.7749,
                  longitude: -122.4194,
                },
                destinationCoordinates: {
                  latitude: 37.7849,
                  longitude: -122.4094,
                },
              },
              lost: {
                assetKind: 'fiat',
              },
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:16]
            try await Candle.Client.shared.getTradeQuotes(.init(
              gained: .TransportAsset(.init(
                assetKind: .transport,
                originCoordinates: .init(
                  latitude: 37.7749,
                  longitude: -122.4194,
                ),
                destinationCoordinates: .init(
                  latitude: 37.7849,
                  longitude: -122.4094,
                ),
              )),
              lost: .FiatAsset(.init(
                assetKind: .fiat,
              )),
            })
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val quotes = Candle.Client.shared.getTradeQuotes(
              request = Models.TradeQuotesRequest(
                gained = Models.OtherAssetQuoteRequest(),
                lost = Models.FiatAssetQuoteRequest(
                  amount = 25.0,
                  currencyCode = "USD",
                ),
                counterparty = Models.ServiceCounterpartyQuoteRequest(
                  service = Models.Service.UBER,
                ),
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val quoteResponse: Models.TradeQuotesResponse = quotes
            val bestQuote: Models.TradeQuote? = quoteResponse.tradeQuotes.firstOrNull()
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Buy $50 of Apple stock</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTradeQuotes(stock, fiat.amount)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:10]
            await candle.getTradeQuotes({
              gained: {
                assetKind: 'stock',
                symbol: 'AAPL',
              },
              lost: {
                assetKind: 'fiat',
                amount: 50,
              },
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:10]
            try await Candle.Client.shared.getTradeQuotes(.init(
              gained: .MarketAsset(.init(
                assetKind: .stock,
                symbol: "AAPL",
              )),
              lost: .FiatAsset(.init(
                assetKind: .fiat,
                amount: 50,
              )),
            })
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val quotes = Candle.Client.shared.getTradeQuotes(
              request = Models.TradeQuotesRequest(
                gained = Models.OtherAssetQuoteRequest(),
                lost = Models.FiatAssetQuoteRequest(
                  amount = 25.0,
                  currencyCode = "USD",
                ),
                counterparty = Models.ServiceCounterpartyQuoteRequest(
                  service = Models.Service.UBER,
                ),
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val quoteResponse: Models.TradeQuotesResponse = quotes
            val bestQuote: Models.TradeQuote? = quoteResponse.tradeQuotes.firstOrNull()
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>

  <Accordion
    title={
    <div className="flex flex-col gap-0.5">
      <span>Buy 10 shares of Apple</span>
      <span className="text-sm font-mono text-muted-foreground">
        getTradeQuotes(stock.amount, fiat)
      </span>
    </div>
  }
  >
    <PlatformTabsRoot className="flex flex-col gap-3 md:flex-row md:items-start md:gap-3 px-3 pb-4 pt-3 md:px-5 md:pb-5md:pt-4">
      <PlatformTabs />

      <Tabs.Content value="react_native" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```ts title="Request"
            import { useCandle } from "react-native-candle"

            const candle = useCandle()

            // [!code highlight:10]
            await candle.getTradeQuotes({
              gained: {
                assetKind: 'stock',
                symbol: 'AAPL',
                amount: 10,
              },
              lost: {
                assetKind: 'fiat',
              },
            })
            ```

            <Callout>
              Get started with the [Candle SDK for React Native](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```ts title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="ios" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```swift title="Request"
            import Candle

            // [!code highlight:10]
            try await Candle.Client.shared.getTradeQuotes(.init(
              gained: .MarketAsset(.init(
                assetKind: .stock,
                symbol: "AAPL",
                amount: 10,
              )),
              lost: .FiatAsset(.init(
                assetKind: .fiat,
              )),
            })
            ```

            <Callout>
              Get started with the [Candle SDK for iOS](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```swift title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="android" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```kotlin title="Request"
            import fi.candle.Candle
            import fi.candle.models.Models

            val quotes = Candle.Client.shared.getTradeQuotes(
              request = Models.TradeQuotesRequest(
                gained = Models.OtherAssetQuoteRequest(),
                lost = Models.FiatAssetQuoteRequest(
                  amount = 25.0,
                  currencyCode = "USD",
                ),
                counterparty = Models.ServiceCounterpartyQuoteRequest(
                  service = Models.Service.UBER,
                ),
              ),
            )
            ```

            <Callout>
              Get started with the [Candle SDK for Android](/setup/install).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```kotlin title="Response"
            import fi.candle.models.Models

            val quoteResponse: Models.TradeQuotesResponse = quotes
            val bestQuote: Models.TradeQuote? = quoteResponse.tradeQuotes.firstOrNull()
            ```
          </div>
        </div>
      </Tabs.Content>

      <Tabs.Content value="flutter" className="flex-1 self-start mt-1 md:mt-0 w-full">
        <div className="grid gap-3 md:grid-cols-2 md:gap-5 w-full">
          <div className="w-full overflow-x-auto">
            ```dart title="Request"
            // Coming Soon
            ```

            <Callout>
              Get early access to the [Candle SDK for Flutter](https://discord.gg/H7jQyjz7s4).
            </Callout>
          </div>

          <div className="w-full overflow-x-auto">
            ```dart title="Response"
            // Coming Soon
            ```
          </div>
        </div>
      </Tabs.Content>
    </PlatformTabsRoot>
  </Accordion>
</Accordions>