Core Concepts

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

​

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.