schema.graphql

type AccountCapabilities {
  """An approved bank account is on file for payouts."""
  bankPayout: Boolean!

  """Business profile (name and address) on file."""
  business: Boolean!

  """
  USD account and routing number available (Bridge KYC approved). Orthogonal to the other capabilities.
  """
  usdAccount: Boolean!

  """Phone and identity verified."""
  verified: Boolean!
}

type AccountDetailPayload {
  accountDetails: AuditedAccount
  errors: [Error]
}

enum AccountLevel {
  ONE
  THREE
  TWO
  ZERO
}

enum AccountStatus {
  ACTIVE
  CLOSED
  LOCKED
  NEW
  PENDING
}

enum AccountStatusHeadline {
  BUSINESS
  TRIAL
  VERIFIED
}

input AccountUpdateLevelInput {
  erpParty: String
  level: AccountLevel!
  uid: ID!
}

input AccountUpdateStatusInput {
  comment: String
  status: AccountStatus!
  uid: ID!
}

"""
Accounts are core to the Galoy architecture. they have users, and own wallets
"""
type AuditedAccount {
  capabilities: AccountCapabilities!

  """
  GPS coordinates for the account that can be used to place the related business on a map
  """
  coordinates: Coordinates
  createdAt: Timestamp!
  erpParty: String
  id: ID!
  level: AccountLevel!
  merchants: [Merchant!]!
  npub: String
  owner: AuditedUser!
  status: AccountStatus!
  statusHeadline: AccountStatusHeadline!
  title: String
  username: Username
  uuid: String!
  wallets: [Wallet!]!
}

type AuditedUser {
  createdAt: Timestamp!

  """Email address"""
  email: Email
  id: ID!
  language: Language!
  phone: Phone
}

"""
A wallet belonging to an account which contains a BTC balance and a list of transactions.
"""
type BTCWallet implements Wallet {
  accountId: ID!

  """A balance stored in BTC."""
  balance: FractionalCentAmount
  id: ID!
  isExternal: Boolean!
  lnurlp: Lnurl

  """An unconfirmed incoming onchain balance."""
  pendingIncomingBalance: SignedAmount!

  """A list of BTC transactions associated with this wallet."""
  transactions(
    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  transactionsByAddress(
    """Returns the items that include this address."""
    address: OnChainAddress!

    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  walletCurrency: WalletCurrency!
}

type BridgeReconciliationOrphan {
  amount: String
  currency: String
  customerId: String
  detectedAt: String!
  id: ID!
  orphanKey: String!
  orphanType: String!
  resolvedAt: String
  status: String!
  transferId: String
  triageContext: String!
  txHash: String
}

input BusinessDeleteMapInfoInput {
  username: Username!
}

input BusinessUpdateMapInfoInput {
  latitude: Float!
  longitude: Float!
  title: String!
  username: Username!
}

type CashWalletCutover {
  completedAt: Timestamp
  cutoverVersion: Int!
  pauseReason: String
  pausedAt: Timestamp
  runId: String
  scheduledAt: Timestamp
  startedAt: Timestamp
  state: CashWalletCutoverState!
  updatedAt: Timestamp!
  updatedBy: String
}

type CashWalletCutoverPayload {
  cashWalletCutover: CashWalletCutover
  errors: [Error!]!
}

input CashWalletCutoverRollbackInput {
  accountId: String
  cutoverVersion: Int!
  dryRun: Boolean
  reason: String!
  runId: String!
}

type CashWalletCutoverRollbackPayload {
  dryRun: Boolean
  eligible: Int
  errors: [Error!]!
  migrationIds: [String]
  requested: Int
  skippedByStatus: [String]
}

enum CashWalletCutoverState {
  COMPLETE
  IN_PROGRESS
  PRE
  ROLLED_BACK
}

input CashWalletCutoverUpdateInput {
  cutoverVersion: Int
  pauseReason: String
  runId: String
  scheduledAt: Timestamp
  state: CashWalletCutoverState!
}

type CashWalletMigration {
  accountId: String!
  attempts: Int!
  balanceMovePaymentTransactionId: String
  completedAt: Timestamp
  cutoverVersion: Int!
  destinationAmountUsdtMicros: String
  destinationStartingBalanceUsdtMicros: String
  destinationUsdtWalletId: String!
  feeAmountUsdCents: String
  feeAmountUsdtMicros: String
  feeReimbursementPaymentTransactionId: String
  id: ID!
  lastError: String
  legacyUsdWalletId: String!
  previousDefaultWalletId: String
  rollbackFromStatus: String
  rollbackPaymentTransactionId: String
  rollbackPointerRestoredAt: Timestamp
  rollbackReason: String
  rollbackRequestedAt: Timestamp
  rollbackRequestedBy: String
  rollbackShortfallPaymentTransactionId: String
  rollbackShortfallUsdtMicros: String
  rolledBackAt: Timestamp
  runId: String!
  sourceBalanceUsdCents: String
  startedAt: Timestamp
  status: String!
  updatedAt: Timestamp!
}

input CashoutNotificationSendInput {
  accountId: String!
  amount: Int!
  currency: String!
}

type Coordinates {
  latitude: Float!
  longitude: Float!
}

"""Display currency of an account"""
scalar DisplayCurrency

type Email {
  address: EmailAddress
  verified: Boolean
}

"""Email address"""
scalar EmailAddress

interface Error {
  code: String
  message: String!
  path: [String]
}

"""
Cent amount (1/100 of a dollar) as a float, can be positive or negative
"""
scalar FractionalCentAmount

type GraphQLApplicationError implements Error {
  code: String
  message: String!
  path: [String]
}

type IdDocumentReadUrlPayload {
  errors: [Error!]!

  """Pre-signed URL for reading the ID document (valid for 1 hour)"""
  readUrl: String
}

union InitiationVia = InitiationViaIntraLedger | InitiationViaLn | InitiationViaOnChain

type InitiationViaIntraLedger {
  counterPartyUsername: Username
  counterPartyWalletId: WalletId
}

type InitiationViaLn {
  paymentHash: PaymentHash!
}

type InitiationViaOnChain {
  address: OnChainAddress!
}

scalar Language

type LightningInvoice {
  confirmedAt: Timestamp
  createdAt: Timestamp!
  description: String!
  expiresAt: Timestamp
  isSettled: Boolean!
  received: SatAmount!
  request: LnPaymentRequest
  secretPreImage: LnPaymentPreImage!
}

type LightningPayment {
  amount: SatAmount
  confirmedAt: Timestamp
  createdAt: Timestamp
  destination: LnPubkey
  request: LnPaymentRequest
  revealedPreImage: LnPaymentPreImage
  roundedUpFee: SatAmount
  status: LnPaymentStatus
}

scalar LnPaymentPreImage

"""BOLT11 lightning invoice payment request with the amount included"""
scalar LnPaymentRequest

scalar LnPaymentSecret

enum LnPaymentStatus {
  FAILED
  PENDING
  SETTLED
}

scalar LnPubkey

"""
A bech32-encoded HTTPS/Onion URL that can be interacted with automatically by a WALLET in a standard way such that a SERVICE can provide extra services or a better experience for the user. Ref: https://github.com/lnurl/luds/blob/luds/01.md 
"""
scalar Lnurl

"""Text field in a lightning payment transaction"""
scalar Memo

type Merchant {
  """
  GPS coordinates for the merchant that can be used to place the related business on a map
  """
  coordinates: Coordinates!
  createdAt: Timestamp!
  id: ID!
  title: String!

  """The username of the merchant"""
  username: Username!

  """Whether the merchant has been validated"""
  validated: Boolean!
}

input MerchantMapDeleteInput {
  id: ID!
}

input MerchantMapValidateInput {
  id: ID!
}

type MerchantPayload {
  errors: [Error!]!
  merchant: Merchant
}

type Mutation {
  accountUpdateLevel(input: AccountUpdateLevelInput!): AccountDetailPayload!
  accountUpdateStatus(input: AccountUpdateStatusInput!): AccountDetailPayload!
  businessDeleteMapInfo(input: BusinessDeleteMapInfoInput!): AccountDetailPayload!
  businessUpdateMapInfo(input: BusinessUpdateMapInfoInput!): AccountDetailPayload!
  cashWalletCutoverRollback(input: CashWalletCutoverRollbackInput!): CashWalletCutoverRollbackPayload!
  cashWalletCutoverUpdate(input: CashWalletCutoverUpdateInput!): CashWalletCutoverPayload!
  cashoutNotificationSend(input: CashoutNotificationSendInput!): SuccessPayload!
  merchantMapDelete(input: MerchantMapDeleteInput!): MerchantPayload!
  merchantMapValidate(input: MerchantMapValidateInput!): MerchantPayload!
  sendNotification(input: SendNotificationInput!): SendNotificationPayload!
  userUpdatePhone(input: UserUpdatePhoneInput!): AccountDetailPayload!
}

scalar NotificationTopic

"""An address for an on-chain bitcoin destination"""
scalar OnChainAddress

scalar OnChainTxHash

"""Information about pagination in a connection."""
type PageInfo {
  """When paginating forwards, the cursor to continue."""
  endCursor: String

  """When paginating forwards, are there more items?"""
  hasNextPage: Boolean!

  """When paginating backwards, are there more items?"""
  hasPreviousPage: Boolean!

  """When paginating backwards, the cursor to continue."""
  startCursor: String
}

scalar PaymentHash

"""Phone number which includes country code"""
scalar Phone

interface PriceInterface {
  base: SafeInt!
  currencyUnit: String! @deprecated(reason: "Deprecated due to type renaming")
  offset: Int!
}

"""
Price of 1 sat or 1 usd cent in base/offset. To calculate, use: `base / 10^offset`
"""
type PriceOfOneSettlementMinorUnitInDisplayMinorUnit implements PriceInterface {
  base: SafeInt!
  currencyUnit: String! @deprecated(reason: "Deprecated due to type renaming")
  formattedAmount: String! @deprecated(reason: "Deprecated please use `base / 10^offset`")
  offset: Int!
}

type Query {
  accountDetailsByAccountId(accountId: ID!): AuditedAccount!
  accountDetailsByEmail(email: EmailAddress!): AuditedAccount!
  accountDetailsByUserPhone(phone: Phone!): AuditedAccount!
  accountDetailsByUsername(username: Username!): AuditedAccount!
  allLevels: [AccountLevel!]!
  bridgeReconciliationOrphans(limit: Int = 50, orphanType: String = null, status: String = null): [BridgeReconciliationOrphan!]!
  cashWalletCutover: CashWalletCutover!
  cashWalletMigrations(cutoverVersion: Int!, runId: String!, statuses: [String]): [CashWalletMigration!]!
  idDocumentReadUrl(
    """Storage key of the ID document file"""
    fileKey: String!
  ): IdDocumentReadUrlPayload!
  lightningInvoice(hash: PaymentHash!): LightningInvoice!
  lightningPayment(hash: PaymentHash!): LightningPayment!
  listWalletIds(walletCurrency: WalletCurrency!): [WalletId!]!
  merchantsPendingApproval: [Merchant!]!
  notificationTopics: [String!]!
  transactionById(id: ID!): Transaction
  transactionDetailsById(id: ID!): TransactionDetails
  transactionsByHash(hash: PaymentHash!): [Transaction]
  wallet(walletId: WalletId!): Wallet!
}

"""
Non-fractional signed whole numeric value between -(2^53) + 1 and 2^53 - 1
"""
scalar SafeInt

"""(Positive) Satoshi amount"""
scalar SatAmount

input SendNotificationInput {
  body: String!
  title: String!
  topic: NotificationTopic!
}

type SendNotificationPayload {
  errors: [Error]
  success: Boolean
}

union SettlementVia = SettlementViaIntraLedger | SettlementViaLn | SettlementViaOnChain

type SettlementViaIntraLedger {
  """
  Settlement destination: Could be null if the payee does not have a username
  """
  counterPartyUsername: Username
  counterPartyWalletId: WalletId
}

type SettlementViaLn {
  paymentSecret: LnPaymentSecret @deprecated(reason: "Shifting property to 'preImage' to improve granularity of the LnPaymentSecret type")
  preImage: LnPaymentPreImage
}

type SettlementViaOnChain {
  transactionHash: OnChainTxHash
  vout: Int
}

"""An amount (of a currency) that can be negative (e.g. in a transaction)"""
scalar SignedAmount

"""
A string amount (of a currency) that can be negative (e.g. in a transaction)
"""
scalar SignedDisplayMajorAmount

type SuccessPayload {
  errors: [Error!]!
  success: Boolean
}

"""
Timestamp field, serialized as Unix time (the number of seconds since the Unix epoch)
"""
scalar Timestamp

"""
Give details about an individual transaction.
Galoy have a smart routing system which is automatically
settling intraledger when both the payer and payee use the same wallet
therefore it's possible the transactions is being initiated onchain
or with lightning but settled intraledger.
"""
type Transaction {
  createdAt: Timestamp!
  direction: TxDirection!
  id: ID!

  """From which protocol the payment has been initiated."""
  initiationVia: InitiationVia!
  memo: Memo

  """Amount of the settlement currency sent or received."""
  settlementAmount: SignedAmount!

  """Wallet currency for transaction."""
  settlementCurrency: WalletCurrency!
  settlementDisplayAmount: SignedDisplayMajorAmount!
  settlementDisplayCurrency: DisplayCurrency!
  settlementDisplayFee: SignedDisplayMajorAmount!
  settlementFee: SignedAmount!

  """Price in WALLETCURRENCY/SETTLEMENTUNIT at time of settlement."""
  settlementPrice: PriceOfOneSettlementMinorUnitInDisplayMinorUnit!

  """To which protocol the payment has settled on."""
  settlementVia: SettlementVia!
  status: TxStatus!
}

"""A connection to a list of items."""
type TransactionConnection {
  """A list of edges."""
  edges: [TransactionEdge!]

  """Information to aid in pagination."""
  pageInfo: PageInfo!
}

type TransactionDetails {
  """Account ID associated with the transaction"""
  accountId: String

  """Bitcoin address for onchain transactions"""
  address: String

  """Transaction amount"""
  amount: Float

  """Number of confirmations for onchain transactions"""
  confirmations: Int

  """Transaction creation timestamp"""
  createdAt: String

  """Transaction currency"""
  currency: String

  """Transaction fee"""
  fee: Float

  """Transaction ID"""
  id: String!

  """Lightning invoice (bolt11)"""
  invoice: String

  """Transaction memo/description"""
  memo: String

  """Lightning payment hash"""
  paymentHash: String

  """Lightning payment preimage"""
  paymentPreimage: String

  """Transaction status"""
  status: String

  """Bitcoin transaction ID for onchain transactions"""
  txid: String

  """Transaction type (lightning/onchain)"""
  type: String

  """Transaction last update timestamp"""
  updatedAt: String

  """Output index for onchain transactions"""
  vout: Int
}

"""An edge in a connection."""
type TransactionEdge {
  """A cursor for use in pagination"""
  cursor: String!

  """The item at the end of the edge"""
  node: Transaction!
}

enum TxDirection {
  RECEIVE
  SEND
}

enum TxStatus {
  FAILURE
  PENDING
  SUCCESS
}

"""
A wallet belonging to an account which contains a USD balance and a list of transactions.
"""
type UsdWallet implements Wallet {
  accountId: ID!
  balance: FractionalCentAmount
  id: ID!
  isExternal: Boolean!
  lnurlp: Lnurl

  """An unconfirmed incoming onchain balance."""
  pendingIncomingBalance: SignedAmount!
  transactions(
    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  transactionsByAddress(
    """Returns the items that include this address."""
    address: OnChainAddress!

    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  walletCurrency: WalletCurrency!
}

"""
A wallet belonging to an account which contains a USDT balance and a list of transactions.
"""
type UsdtWallet implements Wallet {
  accountId: ID!
  balance: FractionalCentAmount
  id: ID!
  isExternal: Boolean!
  lnurlp: Lnurl

  """An unconfirmed incoming onchain balance."""
  pendingIncomingBalance: SignedAmount!
  transactions(
    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  transactionsByAddress(
    """Returns the items that include this address."""
    address: OnChainAddress!

    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  walletCurrency: WalletCurrency!
}

input UserUpdatePhoneInput {
  accountUuid: ID!
  phone: Phone!
}

"""Unique identifier of a user"""
scalar Username

"""
A generic wallet which stores value in one of our supported currencies.
"""
interface Wallet {
  accountId: ID!
  balance: FractionalCentAmount
  id: ID!
  isExternal: Boolean!
  lnurlp: Lnurl
  pendingIncomingBalance: SignedAmount!

  """
  Transactions are ordered anti-chronologically,
  ie: the newest transaction will be first
  """
  transactions(
    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection

  """
  Transactions are ordered anti-chronologically,
  ie: the newest transaction will be first
  """
  transactionsByAddress(
    """Returns the items that include this address."""
    address: OnChainAddress!

    """Returns the items in the list that come after the specified cursor."""
    after: String

    """Returns the items in the list that come before the specified cursor."""
    before: String

    """Returns the first n items from the list."""
    first: Int

    """Returns the last n items from the list."""
    last: Int
  ): TransactionConnection
  walletCurrency: WalletCurrency!
}

enum WalletCurrency {
  BTC
  USD
  USDT
}

"""Unique identifier of a wallet"""
scalar WalletId