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

# Core Concepts

> Core concepts and terminology for the Grid API

There are several key entities in the Grid API: **Platform**, **Customers**, **Internal Accounts**, **External Accounts**, **Quotes**, **Transactions**, and **UMA Addresses**.

<img src="https://mintcdn.com/ramps/iSnT-NB4iMMUe72B/images/entities-light.svg?fit=max&auto=format&n=iSnT-NB4iMMUe72B&q=85&s=3ba9892f76916c7a2e73067f0c9aade6" alt="Entity relationships diagram showing platform, customers, internal accounts, external accounts, transactions, and UMA addresses" className="block dark:hidden" style={{ width: '100%', borderRadius: '8px', marginBottom: '24px' }} width="1018" height="561" data-path="images/entities-light.svg" />

<img src="https://mintcdn.com/ramps/iSnT-NB4iMMUe72B/images/entities-dark.svg?fit=max&auto=format&n=iSnT-NB4iMMUe72B&q=85&s=076e396f4490ed6d9aa00a8d20410208" alt="Entity relationships diagram showing platform, customers, internal accounts, external accounts, transactions, and UMA addresses" className="hidden dark:block" style={{ width: '100%', borderRadius: '8px', marginBottom: '24px' }} width="1018" height="561" data-path="images/entities-dark.svg" />

## Businesses, People, and Accounts

### Platform

Your **platform** is you! It's the top-level entity that integrates with the Grid API. The platform:

* Has its own configuration (webhook endpoint, supported currencies, API tokens, etc.)
* A platform can have many customers both business and individual
* Manages multiple customers and their accounts
* Can hold platform-owned internal accounts for settlement and liquidity management
* Acts as the integration point between your application and the open Money Grid

### Customers

**Customers** are your end users who send and receive payments through your platform. Each customer:

* Can be an individual or business entity
* Has a KYC/KYB status that determines their ability to transact. If you are a regulated financial institution, this will typically be `APPROVED` since you do the KYC/KYB yourself.
* Is identified by both a system-generated ID and optionally your platform-specific customer ID
* May have associated internal accounts and external accounts
* May have a unique **UMA address** (e.g., `$john.doe@yourdomain.com`). If you don't assign an UMA address when creating a customer, they will be assigned a system-generated one.

### Internal Accounts

**Internal accounts** are Grid-managed accounts that hold balances in specific currencies. They can belong to either:

* **Platform internal accounts** - Owned by the platform for settlement, liquidity, and float management
* **Customer internal accounts** - Associated with specific customers for holding funds

Internal accounts:

* Have balances in a single currency (USD, EUR, MXN, etc.)
* Can be funded via bank transfers or crypto deposits using payment instructions
* Are used as sources or destinations for transactions instantly 24/7/365
* Track available balance for sending payments or receiving funds

<Note>
  **Global Accounts** are a special kind of internal account, powered by a self-custody embedded [Spark](https://spark.money) wallet that Grid provisions for your customers to hold a stablecoin balance. They behave like any other internal account on the way in, but every outbound transfer must be authorized by a customer signature. See [Global Accounts](/payouts-and-b2b/global-accounts/overview) for the full overview.
</Note>

### External Accounts

**External accounts** are traditional bank accounts, crypto wallets, or other payment instruments connected to customers
for on-ramping or off-ramping funds. Each external account:

* Are associated with a specific customer or the platform
* Represents a real-world bank account (with routing number, account number, IBAN, etc.), wallet, or payment instrument
* Has an associated beneficiary (individual or business) who receives payments from the customer or platform
* Has a status indicating screening status (ACTIVE, PENDING, INACTIVE, etc.)
* Can be used as a destination for quote-based transfers or same currency transfers like withdrawals
* For pullable sources like debit cards or ACH pulls, an external account can be used as a source for transfers-in to
  fund internal accounts or to fund cross-border transfers via quotes.

## Entity Examples by Use Case

Understanding how entities map to your specific use case helps clarify your integration architecture. Here are common examples:

### B2B Payouts Platform (e.g., Bill.com, Routable)

| Entity Type          | Who They Are                           | Example                                    |
| -------------------- | -------------------------------------- | ------------------------------------------ |
| **Platform**         | The payouts platform itself            | Your company providing AP automation       |
| **Customer**         | Businesses sending payments to vendors | Acme Corp (your client company)            |
| **External Account** | Vendors/suppliers receiving payments   | Office supply vendor, freelance contractor |

**Flow**: Acme Corp (customer) uses your platform to pay their vendor invoices → funds move from Acme's internal account → to vendor's external bank account

### Direct Rewards Platform (Platform-Funded Model)

| Entity Type          | Who They Are                                | Example                             |
| -------------------- | ------------------------------------------- | ----------------------------------- |
| **Platform**         | The app paying rewards directly to users    | Your cashback app                   |
| **Customer**         | (Not used in this model)                    | N/A                                 |
| **External Account** | End users' crypto wallets receiving rewards | Sarah's self-custody Bitcoin wallet |

**Flow**: Your platform sends micro-payouts directly from platform internal accounts → to users' external crypto wallets at scale. Common for cashback apps where the platform earns affiliate commissions and shares them with users.

### White-Label Rewards Platform (Customer-Funded Model)

| Entity Type          | Who They Are                                 | Example                             |
| -------------------- | -------------------------------------------- | ----------------------------------- |
| **Platform**         | The rewards infrastructure provider          | Your white-label rewards API        |
| **Customer**         | Brands or merchants running reward campaigns | Nike, Starbucks                     |
| **External Account** | End users' crypto wallets receiving rewards  | Sarah's self-custody Bitcoin wallet |

**Flow**: Nike (customer) funds their internal account → your platform sends rewards on their behalf → to users' external crypto wallets. Common for brand loyalty programs where merchants manage their own reward budgets.

### Remittance/P2P App (e.g., Wise, Remitly)

| Entity Type          | Who They Are                        | Example                                                          |
| -------------------- | ----------------------------------- | ---------------------------------------------------------------- |
| **Platform**         | The remittance service              | Your money transfer app                                          |
| **Customer**         | Both sender and recipient of funds  | Maria (sender in US), Juan (recipient in Mexico)                 |
| **External Account** | Bank accounts for funding/receiving | Maria's US bank (funding), Juan's Mexican bank (receiving funds) |

**Flow**: Maria (customer) funds transfer from her external account → to Juan (also a customer) → who receives funds in his external bank account. Alternatively, Maria could send to Juan's UMA address directly.

## Transactions and Addressing Entities

### Quotes

**Quotes** provide locked-in exchange rates and payment instructions for transfers. A quote:

* Specifies a source (internal account, customer ID, or the platform itself) and destination (internal/external account or UMA address)
* Locks an exchange rate for a short period (typically 1-5 minutes) or can be immediately executed with the `immediatelyExecute` flag
* Calculates total fees and amounts for currency conversion
* Provides payment instructions for funding the transfer if needed, or can be funded via an internal account balance.
* Must be executed before it expires
* Creates a transaction when executed

### Transactions

**Transactions** represent completed or in-progress payment transfers. Each transaction:

* Has a type (INCOMING or OUTGOING from the platform's perspective)
* Has a status (PENDING, COMPLETED, FAILED, etc.)
* References a customer (sender for outgoing, recipient for incoming) or a platform internal account
* Specifies source and destination (accounts or UMA addresses)
* Includes amounts, currencies, and settlement information
* May include counterparty information for compliance purposes if required by your platform configuration

Transactions are created when:

* A quote is executed (either incoming or outgoing)
* A same currency transfer is initiated (transfer-in or transfer-out)

### UMA Addresses (optional)

**UMA addresses** are human-readable payment identifiers that follow the format `$username@domain.com`. They:

* Uniquely identify entities on the Grid network
* Enable sending and receiving payments across different platforms without knowing the recipient's underlying account details or personal information
* Support currency negotiation and cross-border transfers
* Work similar to email addresses but for payments
* Are an optional UX improvement for some use cases. Use of UMA addresses is not required in order to use the Grid API.