schema.graphql

"""
Accounts are core to the Galoy architecture. they have users, and own wallets
"""
type Account {
  """
  GPS coordinates for the account that can be used to place the related business on a map
  """
  coordinates: Coordinates
  createdAt: Timestamp!
  id: ID!
  level: AccountLevel!
  owner: User!
  status: AccountStatus!
  title: String
  username: Username
  wallets: [Wallet!]!
}

type AccountDetailPayload {
  accountDetails: Account
  errors: [Error!]!
}

enum AccountLevel {
  ONE
  TWO
}

enum AccountStatus {
  ACTIVE
  LOCKED
  NEW
  PENDING
}

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

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

input AccountsAddUsdWalletInput {
  accountIds: [ID!]!
}

"""
An Opaque Bearer token
"""
scalar AuthToken

type AuthTokenPayload {
  authToken: AuthToken
  errors: [Error!]!
}

"""
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: SignedAmount!
  id: ID!

  """
  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!
}

input BusinessDeleteMapInfoInput {
  username: Username!
}

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

type CaptchaCreateChallengePayload {
  errors: [Error!]!
  result: CaptchaCreateChallengeResult
}

type CaptchaCreateChallengeResult {
  challengeCode: String!
  failbackMode: Boolean!
  id: String!
  newCaptcha: Boolean!
}

input CaptchaRequestAuthCodeInput {
  challengeCode: String!
  channel: PhoneCodeChannelType
  phone: Phone!
  secCode: String!
  validationCode: String!
}

input ColdStorageRebalanceToHotWalletInput {
  amount: SatAmount!
  targetConfirmations: TargetConfirmations = 1
  walletName: String!
}

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

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

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

type GraphQLApplicationError implements Error {
  code: String
  message: String!
  path: [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

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

type Mutation {
  accountUpdateLevel(input: AccountUpdateLevelInput!): AccountDetailPayload!
  accountUpdateStatus(input: AccountUpdateStatusInput!): AccountDetailPayload!
  accountsAddUsdWallet(input: AccountsAddUsdWalletInput!): WalletDetailsPayload
  businessDeleteMapInfo(input: BusinessDeleteMapInfoInput!): AccountDetailPayload!
  businessUpdateMapInfo(input: BusinessUpdateMapInfoInput!): AccountDetailPayload!
  captchaCreateChallenge: CaptchaCreateChallengePayload!
  captchaRequestAuthCode(input: CaptchaRequestAuthCodeInput!): SuccessPayload!
  coldStorageRebalanceToHotWallet(
    input: ColdStorageRebalanceToHotWalletInput!
  ): PsbtDetailPayload!
  userLogin(input: UserLoginInput!): AuthTokenPayload!
  userRequestAuthCode(input: UserRequestAuthCodeInput!): SuccessPayload!
  userUpdatePhone(input: UserUpdatePhoneInput!): AccountDetailPayload!
}

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

scalar OnChainTxHash

"""
An authentication code valid for a single use
"""
scalar OneTimeAuthCode

"""
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

enum PhoneCodeChannelType {
  SMS
  WHATSAPP
}

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 PsbtDetail {
  fee: SatAmount!
  transaction: String!
}

type PsbtDetailPayload {
  errors: [Error!]!
  psbtDetail: PsbtDetail
}

type Query {
  accountDetailsByUserPhone(phone: Phone!): Account!
  accountDetailsByUsername(username: Username!): Account!
  allLevels: [AccountLevel!]!
  lightningInvoice(hash: PaymentHash!): LightningInvoice!
  lightningPayment(hash: PaymentHash!): LightningPayment!
  listWalletIds(walletCurrency: WalletCurrency!): [WalletId!]!
  transactionById(id: ID!): Transaction
  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

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!
}

"""
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
}

"""
(Positive) Number of blocks in which the transaction is expected to be confirmed
"""
scalar TargetConfirmations

"""
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!
}

"""
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: SignedAmount!
  id: ID!

  """
  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!
}

type User {
  createdAt: Timestamp!
  defaultAccount: Account!
  id: ID!
  language: Language!
  phone: Phone!
}

input UserLoginInput {
  code: OneTimeAuthCode!
  phone: Phone!
}

input UserRequestAuthCodeInput {
  channel: PhoneCodeChannelType
  phone: Phone!
}

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

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

"""
A generic wallet which stores value in one of our supported currencies.
"""
interface Wallet {
  accountId: ID!
  balance: SignedAmount!
  id: ID!
  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
}

type WalletDetailsPayload {
  errors: [Error!]!
  walletDetails: [Wallet!]!
}

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