> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onconsul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building a New Marketplace with Consul

> Build a marketplace with buyer Consul accounts, escrow, and seller payouts

This guide covers a more advanced marketplace integration where buyers have their own Consul accounts connected via
OAuth. Funds flow from the buyer's account into your platform's central Consul account (escrow), and you release
them to sellers when conditions are met. If you don't need escrow or user-facing Consul accounts, see the simpler
[Adding Payouts to a Marketplace](/guides/tutorials/marketplace) tutorial.

## Prerequisites

| What                                                             | Why                                                      | Where to get it                              |
| ---------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------- |
| Consul API key                                                   | Authenticate requests from your central (escrow) account | [Dashboard](https://dashboard.onconsul.com)  |
| OAuth credentials (`client_id`, `client_secret`, `redirect_uri`) | Connect buyer Consul accounts to your app                | Provided during app registration with Consul |
| Webhook endpoint                                                 | Track payout and deposit status updates                  | [Events and Webhooks](/guides/webhooks)      |

## Architecture

Two sets of credentials are in play:

* **OAuth access tokens** (per buyer) — used to move funds *from* a buyer's Consul balance during checkout.
* **API key** (your central account) — used to release funds *to* sellers on completion.

```mermaid theme={"system"}
sequenceDiagram
    participant Buyer
    participant YourApp as Your App
    participant Escrow as "Consul (Your Account)"
    participant BuyerWallet as "Consul (Buyer Account)"

    Buyer->>YourApp: Link Consul account
    YourApp->>BuyerWallet: OAuth authorization flow
    BuyerWallet-->>YourApp: Access token

    Buyer->>YourApp: Checkout
    YourApp->>BuyerWallet: Payout to your account (buyer's OAuth token)
    BuyerWallet-->>Escrow: USDC transfer

    Note over YourApp,Escrow: Funds held in escrow

    YourApp->>Escrow: Payout to seller's email (API key)
```

## Connect Buyer Accounts

Use the [OAuth authorization code flow](/guides/oauth) to let buyers link their Consul accounts. When a buyer
connects, you receive an access token scoped to their account. Store it (along with the refresh token) per user.

The buyer sees a Consul consent screen and grants your app permission to initiate transfers on their behalf. See
the [OAuth Connections](/guides/oauth) guide for the full implementation, including token refresh and revocation.

## Checkout: Collect Funds into Escrow

When a buyer checks out, use their OAuth access token to call [Create a Payout](/api-reference/payouts/create-a-payout)
on their behalf. The payout recipient is your platform's own Consul account (by email or recipient ID). This moves
USDC from the buyer's balance into yours - effectively placing funds in escrow.

Before initiating the payout, check the buyer's balance via [GET /balance](/api-reference/accounts/get-consul-balance)
(using their OAuth token). If the balance is insufficient, you can request deposit instructions via the
[Deposits API](/api-reference/deposits/create-a-deposit-quote) on their behalf so they can fund their account.
Listen for the `deposit.updated` [webhook](/guides/webhooks) to know when funds arrive, then notify the buyer
that their balance is ready and they can complete checkout.

## Release: Payout to Seller

When your platform's conditions are met - delivery confirmed, milestone completed, dispute resolved - release funds
to the seller by calling [Create a Payout](/api-reference/payouts/create-a-payout) with your API key. Target the
seller by email. If the seller doesn't have a Consul account yet, they'll receive an email invite to claim their
funds.

Track settlement via `payout.updated` [webhooks](/guides/webhooks) or by polling the
[Payouts API](/api-reference/payouts/get-a-payout).

## Creating a Wallet UI

With OAuth, you can surface each buyer's Consul account details directly in your UI - effectively white-labelling Consul as a
wallet in your platform. Use the buyer's OAuth token to:

* **Show their balance** via [GET /balance](/api-reference/accounts/get-consul-balance)
* **List their transactions and statuses** via [GET /transactions](/api-reference/transactions/list-transactions)
* **Create deposits** via [Create a Deposit](/api-reference/deposits/create-a-deposit)

This lets buyers view their funds and transaction history without ever leaving your app.

## Refunds

If a dispute is resolved in the buyer's favor, issue a payout from your central account back to the buyer's email
using the same [Create a Payout](/api-reference/payouts/create-a-payout) endpoint.