schema.graphql

interface Account {
  csvTransactions(walletIds: [WalletId!]!): String!
  defaultWalletId: WalletId!
  id: ID!
  wallets: [Wallet!]!
}

type AccountApiKey {
  expireAt: Timestamp!
  key: String!
  label: AccountApiKeyLabel!
  secret: String!
}

input AccountApiKeyCreateInput {
  expireAt: Timestamp!
  label: AccountApiKeyLabel
}

input AccountApiKeyDisableInput {
  label: AccountApiKeyLabel!
}

type AccountApiKeyHashed {
  expireAt: Timestamp!
  label: AccountApiKeyLabel!
}

"""
Identifier of an account api key
"""
scalar AccountApiKeyLabel

type AccountApiKeyPayload {
  accountApiKey: AccountApiKey
  errors: [Error!]!
}

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

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

type BTCWallet implements Wallet {
  balance: SignedAmount!
  id: ID!
  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
  walletCurrency: WalletCurrency!
}

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

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

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

type ConsumerAccount implements Account {
  csvTransactions(walletIds: [WalletId!]!): String!
  defaultWalletId: WalletId!
  id: ID!
  wallets: [Wallet!]!
}

"""
An alias name that a user can set for a wallet (with which they have transactions)
"""
scalar ContactAlias

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

input DeviceNotificationTokenCreateInput {
  deviceToken: String!
}

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

enum ExchangeCurrencyUnit {
  BTCSAT
  USDCENT
}

"""
Provides global settings for the application which might have an impact for the user.
"""
type Globals {
  """
  A list of public keys for the running lightning nodes.
  This can be used to know if an invoice belongs to one of our nodes.
  """
  nodesIds: [String!]!
}

"""
Hex-encoded string of 32 bytes
"""
scalar Hex32Bytes

union InitiationVia = InitiationViaIntraLedger | InitiationViaLn | InitiationViaOnChain

type InitiationViaIntraLedger {
  counterPartyUsername: Username
  counterPartyWalletId: WalletId
}

type InitiationViaLn {
  paymentHash: PaymentHash!
}

type InitiationViaOnChain {
  address: OnChainAddress!
}

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

enum InputErrorCode {
  INVALID_INPUT
  VALUE_NOT_ALLOWED
  VALUE_TOO_LONG
  VALUE_TOO_SHORT
}

input IntraLedgerPaymentSendInput {
  amount: SatAmount!
  memo: Memo
  recipientWalletId: WalletId!
  walletId: WalletId!
}

type IntraLedgerUpdate {
  amount: SatAmount!
  txNotificationType: TxNotificationType!
  usdPerSat: Float!
}

enum InvoicePaymentStatus {
  PAID
  PENDING
}

scalar Language

type LnInvoice {
  paymentHash: PaymentHash!
  paymentRequest: LnPaymentRequest!
  paymentSecret: LnPaymentSecret!
  satoshis: SatAmount
}

input LnInvoiceCreateInput {
  amount: SatAmount!
  memo: Memo
  walletId: WalletId!
}

input LnInvoiceCreateOnBehalfOfRecipientInput {
  amount: SatAmount!
  descriptionHash: Hex32Bytes
  memo: Memo
  recipientWalletId: WalletId!
}

input LnInvoiceFeeProbeInput {
  paymentRequest: LnPaymentRequest!
  walletId: WalletId!
}

type LnInvoicePayload {
  errors: [Error!]!
  invoice: LnInvoice
}

input LnInvoicePaymentInput {
  memo: Memo
  paymentRequest: LnPaymentRequest!
  walletId: WalletId!
}

input LnInvoicePaymentStatusInput {
  paymentRequest: LnPaymentRequest!
}

type LnInvoicePaymentStatusPayload {
  errors: [Error!]!
  status: InvoicePaymentStatus
}

type LnNoAmountInvoice {
  paymentHash: PaymentHash!
  paymentRequest: LnPaymentRequest!
  paymentSecret: LnPaymentSecret!
}

input LnNoAmountInvoiceCreateInput {
  memo: Memo
  walletId: WalletId!
}

input LnNoAmountInvoiceCreateOnBehalfOfRecipientInput {
  memo: Memo
  recipientWalletId: WalletId!
}

input LnNoAmountInvoiceFeeProbeInput {
  amount: SatAmount!
  paymentRequest: LnPaymentRequest!
  walletId: WalletId!
}

type LnNoAmountInvoicePayload {
  errors: [Error!]!
  invoice: LnNoAmountInvoice
}

input LnNoAmountInvoicePaymentInput {
  amount: SatAmount!
  memo: Memo
  paymentRequest: LnPaymentRequest!
  walletId: WalletId!
}

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

scalar LnPaymentSecret

type LnUpdate {
  paymentHash: PaymentHash!
  status: InvoicePaymentStatus!
}

type MapInfo {
  coordinates: Coordinates!
  title: String!
}

type MapMarker {
  mapInfo: MapInfo!
  username: Username
}

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

type MobileVersions {
  currentSupported: Int!
  minSupported: Int!
  platform: String!
}

type Mutation {
  accountApiKeyCreate(input: AccountApiKeyCreateInput!): AccountApiKeyPayload!
  accountApiKeyDisable(input: AccountApiKeyDisableInput!): SuccessPayload!
  captchaCreateChallenge: CaptchaCreateChallengePayload!
  captchaRequestAuthCode(input: CaptchaRequestAuthCodeInput!): SuccessPayload!
  deviceNotificationTokenCreate(
    input: DeviceNotificationTokenCreateInput!
  ): SuccessPayload!
  intraLedgerPaymentSend(input: IntraLedgerPaymentSendInput!): PaymentSendPayload!
  lnInvoiceCreate(input: LnInvoiceCreateInput!): LnInvoicePayload!
  lnInvoiceCreateOnBehalfOfRecipient(
    input: LnInvoiceCreateOnBehalfOfRecipientInput!
  ): LnInvoicePayload!
  lnInvoiceFeeProbe(input: LnInvoiceFeeProbeInput!): SatAmountPayload!
  lnInvoicePaymentSend(input: LnInvoicePaymentInput!): PaymentSendPayload!
  lnNoAmountInvoiceCreate(input: LnNoAmountInvoiceCreateInput!): LnNoAmountInvoicePayload!
  lnNoAmountInvoiceCreateOnBehalfOfRecipient(
    input: LnNoAmountInvoiceCreateOnBehalfOfRecipientInput!
  ): LnNoAmountInvoicePayload!
  lnNoAmountInvoiceFeeProbe(input: LnNoAmountInvoiceFeeProbeInput!): SatAmountPayload!
  lnNoAmountInvoicePaymentSend(input: LnNoAmountInvoicePaymentInput!): PaymentSendPayload!
  onChainAddressCreate(input: OnChainAddressCreateInput!): OnChainAddressPayload!
  onChainAddressCurrent(input: OnChainAddressCurrentInput!): OnChainAddressPayload!
  onChainPaymentSend(input: OnChainPaymentSendInput!): PaymentSendPayload!
  onChainPaymentSendAll(input: OnChainPaymentSendAllInput!): PaymentSendPayload!
  twoFADelete(input: TwoFADeleteInput!): SuccessPayload!
  twoFAGenerate: TwoFAGeneratePayload!
  twoFASave(input: TwoFASaveInput!): SuccessPayload!
  userContactUpdateAlias(
    input: UserContactUpdateAliasInput!
  ): UserContactUpdateAliasPayload!
  userLogin(input: UserLoginInput!): AuthTokenPayload!
  userQuizQuestionUpdateCompleted(
    input: UserQuizQuestionUpdateCompletedInput!
  ): UserQuizQuestionUpdateCompletedPayload!
  userRequestAuthCode(input: UserRequestAuthCodeInput!): SuccessPayload!
  userUpdateLanguage(input: UserUpdateLanguageInput!): UserUpdateLanguagePayload!
  userUpdateUsername(input: UserUpdateUsernameInput!): UserUpdateUsernamePayload!
}

type MyUpdatesPayload {
  errors: [Error!]!
  me: User
  update: UserUpdate
}

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

input OnChainAddressCreateInput {
  walletId: WalletId!
}

input OnChainAddressCurrentInput {
  walletId: WalletId!
}

type OnChainAddressPayload {
  address: OnChainAddress
  errors: [Error!]!
}

input OnChainPaymentSendAllInput {
  address: OnChainAddress!
  memo: Memo
  targetConfirmations: TargetConfirmations = 1
  walletId: WalletId!
}

input OnChainPaymentSendInput {
  address: OnChainAddress!
  amount: SatAmount!
  memo: Memo
  targetConfirmations: TargetConfirmations = 1
  walletId: WalletId!
}

type OnChainTxFee {
  amount: SatAmount!
  targetConfirmations: TargetConfirmations!
}

scalar OnChainTxHash

type OnChainUpdate {
  amount: SatAmount!
  txHash: OnChainTxHash!
  txNotificationType: TxNotificationType!
  usdPerSat: Float!
}

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

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

enum PaymentErrorCode {
  ACCOUNT_LOCKED
  INSUFFICENT_BALANCE
  INVOICE_PAID
  LIMIT_EXCEEDED
  NO_LIQUIDITY
  NO_ROUTE
}

scalar PaymentHash

type PaymentSendPayload {
  errors: [Error!]!
  status: PaymentSendResult
}

enum PaymentSendResult {
  ALREADY_PAID
  FAILURE
  PENDING
  SUCCESS
}

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

"""
Price amount expressed in base/offset. To calculate, use: `base / 10^offset`
"""
type Price {
  base: SafeInt!
  currencyUnit: ExchangeCurrencyUnit!
  formattedAmount: String!
  offset: Int!
}

"""
The range for the X axis in the BTC price graph
"""
enum PriceGraphRange {
  FIVE_YEARS
  ONE_DAY
  ONE_MONTH
  ONE_WEEK
  ONE_YEAR
}

input PriceInput {
  amount: SatAmount!
  amountCurrencyUnit: ExchangeCurrencyUnit!
  priceCurrencyUnit: ExchangeCurrencyUnit!
}

type PricePayload {
  errors: [Error!]!
  price: Price
}

type PricePoint {
  price: Price!

  """
  Unix timesamp (number of seconds elapsed since January 1, 1970 00:00:00 UTC)
  """
  timestamp: Timestamp!
}

type Query {
  accountApiKeys: [AccountApiKeyHashed]
  btcPriceList(range: PriceGraphRange!): [PricePoint]
  businessMapMarkers: [MapMarker]
  globals: Globals
  me: User
  mobileVersions: [MobileVersions]
  onChainTxFee(
    address: OnChainAddress!
    amount: SatAmount!
    targetConfirmations: TargetConfirmations = 1
    walletId: WalletId!
  ): OnChainTxFee!
  quizQuestions: [QuizQuestion]
  userDefaultWalletId(username: Username!): WalletId!
  usernameAvailable(username: Username!): Boolean
}

type QuizQuestion {
  """
  The earn reward in Satoshis for the quiz question
  """
  earnAmount: SatAmount!
  id: ID!
}

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

"""
(Positive) Satoshi amount (i.g. quiz earning)
"""
scalar SatAmount

type SatAmountPayload {
  amount: SatAmount
  errors: [Error!]!
}

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
}

type SettlementViaOnChain {
  transactionHash: OnChainTxHash!
}

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

type Subscription {
  lnInvoicePaymentStatus(
    input: LnInvoicePaymentStatusInput!
  ): LnInvoicePaymentStatusPayload!
  myUpdates: MyUpdatesPayload!
  price(input: PriceInput!): PricePayload!
}

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 sats paid by the user.
  """
  settlementAmount: SatAmount!
  settlementFee: SatAmount!

  """
  Price in USDCENT/SATS at time of settlement.
  """
  settlementPrice: Price!

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

input TwoFADeleteInput {
  token: String!
}

type TwoFAGeneratePayload {
  errors: [Error!]!
  twoFASecret: TwoFASecret
}

input TwoFASaveInput {
  secret: String!
  token: String!
}

type TwoFASecret {
  secret: String!
  uri: String!
}

enum TxDirection {
  RECEIVE
  SEND
}

enum TxNotificationType {
  IntraLedgerPayment
  IntraLedgerReceipt
  LnInvoicePaid
  OnchainPayment
  OnchainReceipt
  OnchainReceiptPending
}

enum TxStatus {
  FAILURE
  PENDING
  SUCCESS
}

type User {
  """
  Get single contact details.
  Can include the transactions associated with the contact.
  """
  contactByUsername(username: Username!): UserContact!

  """
  Get full list of contacts.
  Can include the transactions associated with each contact.
  """
  contacts: [UserContact!]!
  createdAt: Timestamp!
  defaultAccount: Account!
  id: ID!

  """
  Preferred language for user.
  When value is 'default' the intent is to use preferred language from OS settings.
  """
  language: Language!

  """
  Phone number with international calling code.
  """
  phone: Phone!

  """
  List the quiz questions the user may have completed.
  """
  quizQuestions: [UserQuizQuestion!]!
  twoFAEnabled: Boolean

  """
  Optional immutable user friendly identifier.
  """
  username: Username
}

type UserContact {
  """
  Alias the user can set for this contact.
  Only the user can see the alias attached to their contact.
  """
  alias: ContactAlias
  id: Username!

  """
  Paginated list of transactions sent to/from this contact.
  """
  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
  transactionsCount: Int!

  """
  Actual identifier of the contact.
  """
  username: Username!
}

input UserContactUpdateAliasInput {
  alias: ContactAlias!
  username: Username!
}

type UserContactUpdateAliasPayload {
  contact: UserContact
  errors: [Error!]!
}

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

type UserQuizQuestion {
  completed: Boolean!
  question: QuizQuestion!
}

input UserQuizQuestionUpdateCompletedInput {
  id: ID!
}

type UserQuizQuestionUpdateCompletedPayload {
  errors: [Error!]!
  userQuizQuestion: UserQuizQuestion
}

input UserRequestAuthCodeInput {
  phone: Phone!
}

union UserUpdate = IntraLedgerUpdate | LnUpdate | OnChainUpdate | Price

input UserUpdateLanguageInput {
  language: Language!
}

type UserUpdateLanguagePayload {
  errors: [Error!]!
  user: User
}

input UserUpdateUsernameInput {
  username: Username!
}

type UserUpdateUsernamePayload {
  errors: [Error!]!
  user: User
}

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

interface Wallet {
  balance: SignedAmount!
  id: ID!
  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
  walletCurrency: WalletCurrency!
}

enum WalletCurrency {
  BTC
}

"""
Unique identifier of a user
"""
scalar WalletId