> ## 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.
# Entities & Relationships
> Understanding Grid's core data model
There are several key entities in the Grid API: **Platform**, **Customers**, **Internal Accounts**, **External Accounts**, **Quotes**, **Transactions**, and **UMA Addresses**.
## 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
**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.
### 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.
## Platform Configuration
Your **platform configuration** defines global settings for your Grid integration:
* **Webhook endpoint**: URL where Grid sends event notifications
* **Supported currencies**: Which currencies your platform offers
* **UMA domain** (optional): Your domain for UMA addresses (e.g., `yourplatform.com`)
* **Required counterparty fields** (UMA only): Information required from senders for compliance
Platform configuration is managed via the [dashboard](https://app.lightspark.com).
## ID Format
All Grid entities use a consistent ID format:
```
EntityType:UUID
```
Examples:
* `Customer:019542f5-b3e7-1d02-0000-000000000001`
* `InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965`
* `Transaction:019542f5-b3e7-1d02-0000-000000000030`
* `Quote:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123`
This format makes IDs self-documenting and easier to debug.
## Platform Customer ID
When creating customers, you can provide your own `platformCustomerId`:
```json theme={null}
{
"platformCustomerId": "user_12345_from_my_system",
"customerType": "INDIVIDUAL",
"fullName": "Alice Johnson"
}
```
This allows you to:
* Map Grid customers to your internal user IDs
* Query transactions by your own customer identifiers
* Maintain referential integrity between systems
Grid returns both IDs in all customer-related responses:
```json theme={null}
{
"id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"platformCustomerId": "user_12345_from_my_system"
}
```
## Amount Representation
All monetary amounts in Grid are represented in the **smallest currency unit**:
**Cents, pence, centavos, etc.**
```json theme={null}
{
"amount": 50000,
"currency": {
"code": "USD",
"symbol": "$",
"decimals": 2
}
}
```
This represents **\$500.00** (50000 cents)
**Satoshis for Bitcoin**
```json theme={null}
{
"amount": 10000000,
"currency": {
"code": "BTC",
"symbol": "₿",
"decimals": 8
}
}
```
This represents **0.1 BTC** (10,000,000 satoshis)
The `decimals` field tells you how many decimal places to use when displaying the amount:
```javascript theme={null}
function formatAmount(amount, currency) {
const value = amount / Math.pow(10, currency.decimals);
return `${currency.symbol}${value.toFixed(currency.decimals)}`;
}
// formatAmount(50000, {code: "USD", symbol: "$", decimals: 2}) → "$500.00"
// formatAmount(10000000, {code: "BTC", symbol: "₿", decimals: 8}) → "₿0.10000000"
```
## Timestamps
All timestamps in Grid use **ISO 8601 format with UTC timezone**:
```json theme={null}
{
"createdAt": "2025-10-03T15:00:00Z",
"settledAt": "2025-10-03T15:30:00Z"
}
```
Key timestamp fields:
* **createdAt**: When the entity was created
* **updatedAt**: Last modification time
* **settledAt**: When a transaction completed (transactions only)
* **expiresAt**: When a quote expires (quotes only)