Entities & Relationships

​

Businesses, People, and Accounts

​

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

• 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

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

• 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

• 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

​

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

​

Direct Rewards Platform (Platform-Funded Model)

​

White-Label Rewards Platform (Customer-Funded Model)

​

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

​

Transactions and Addressing Entities

​

Quotes

• 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

• 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

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

​

UMA Addresses (optional)

• 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

• 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

​

ID Format

EntityType:UUID

• Customer:019542f5-b3e7-1d02-0000-000000000001
• InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
• Transaction:019542f5-b3e7-1d02-0000-000000000030
• Quote:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123

​

Platform Customer ID

{
  "platformCustomerId": "user_12345_from_my_system",
  "customerType": "INDIVIDUAL",
  "fullName": "Alice Johnson"
}

• Map Grid customers to your internal user IDs
• Query transactions by your own customer identifiers
• Maintain referential integrity between systems

{
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "user_12345_from_my_system"
}

​

Amount Representation

{
  "amount": 50000,
  "currency": {
    "code": "USD",
    "symbol": "$",
    "decimals": 2
  }
}

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

{
  "createdAt": "2025-10-03T15:00:00Z",
  "settledAt": "2025-10-03T15:30:00Z"
}

• createdAt: When the entity was created
• updatedAt: Last modification time
• settledAt: When a transaction completed (transactions only)
• expiresAt: When a quote expires (quotes only)