Core API Reference

API Endpoints
https://api.staging.galoy.io/graphql
Galoy API Tutorial
Lightning Integration
Overview
The staging API endpoint is: https://api.staging.galoy.io/graphql
Authentication
To get a new JWT:
1.Use userRequestAuthCode to receive an auth code via SMS
2.Call userLogin using the same phone number and auth code
All other methods require a valid JWT set in the header as a bearer token - Authorization: Bearer
Curl requests
userRequestAuthCode
query
export URI=https://api.staging.galoy.io/graphql
export PHONE='+12025550148'
curl --location --request POST $URI --header 'Content-Type: application/json' --data-raw '{"query":"mutation userRequestAuthCode ($input: UserRequestAuthCodeInput!) {\n    userRequestAuthCode (input: $input) {\n        errors {\n            message\n            path\n        }\n        success\n    }\n}","variables":{"input":{"phone":"'"$PHONE"'"}}}'
response
{
    "data": {
        "userRequestAuthCode": {
            "errors": [],
            "success": true
        }
    }
}
userLogin
query
export CODE='012345'
curl --location --request POST $URI --header 'Content-Type: application/json' --data-raw '{"query":"mutation userLogin ($input: UserLoginInput!) {\n    userLogin (input: $input) {\n        errors {\n            message\n            path\n        }\n        authToken\n    }\n}","variables":{"input":{"phone":"'"$PHONE"'","code":"'"$CODE"'"}}}'
response
{
    "data": {
        "userLogin": {
            "errors": [],
            "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI1ZjkwMTY3ODM2MmZmNjIzMjVkZmFmYjciLCJuZXR3b3JrIjoicmVndGVzdCIsImN1cnJlbmN5IjoiQlRDIiwiaWF0IjoxNjAzMjc4NDU2fQ.-im7fJS_andM32zNXDVqSDPPoQtCtCE22X-hUclT3u0"
        }
    }
}
lnInvoiceCreate
query
export AUTH_TOKEN='Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI1ZjkwMTY3ODM2MmZmNjIzMjVkZmFmYjciLCJuZXR3b3JrIjoicmVndGVzdCIsImN1cnJlbmN5IjoiQlRDIiwiaWF0IjoxNjAzMjc4NDU2fQ.-im7fJS_andM32zNXDVqSDPPoQtCtCE22X-hUclT3u0'
export AMOUNT=12345
export MEMO='tipping'
curl --location --request POST $URI --header "$AUTH_TOKEN" --header 'Content-Type: application/json' --data-raw '{"query":"mutation lnInvoiceCreate ($input: LnInvoiceCreateInput!) {\n    lnInvoiceCreate (input: $input) {\n        errors {\n            message\n            path\n        }\n        invoice {\n            paymentRequest\n            paymentHash\n            paymentSecret\n            satoshis\n        }\n    }\n}","variables":{"input":{"amount":"'"$AMOUNT"'","memo":"'"$MEMO"'"}}}'
response
{
    "data": {
        "lnInvoiceCreate": {
            "errors": [],
            "invoice": {
                "paymentRequest": "lntb123450n1pscxulepp59x872uskmr0a4r3wnr3vkmr297zm53smw8j4efevpknuwm8vs5yqdq5w35hqurfdenjq6nsdamscqzpuxqyz5vqsp5yzmznk5z7xszkgfk5xstuh8j5gg4srerelv58pph5wjan2kd8rqs9qyyssqe5l376x893374kqsr5lc8tesudg4jryaqlzmx44mfr87nds83margfa09ggd92sy0rudl6r79sat4rxqml5yfdhmm7yk9jc0ugzw7hgpdfxfzk",
                "paymentHash": "298be57216d8dfda8e2e88e2cb6c6a2f85ba461b71e55ca72c0da7c76cec8508",
                "paymentSecret": "20b629da82f1a02b2136a1a0be5cf2a211580f23cfd8438437a3a5d9aacd38c1",
                "satoshis": 12345
            }
        }
    }
}
lnInvoiceFeeProbe
query
export PAYMENT_REQUEST='lntb123450n1pscxulepp59x872uskmr0a4r3wnr3vkmr297zm53smw8j4efevpknuwm8vs5yqdq5w35hqurfdenjq6nsdamscqzpuxqyz5vqsp5yzmznk5z7xszkgfk5xstuh8j5gg4srerelv58pph5wjan2kd8rqs9qyyssqe5l376x893374kqsr5lc8tesudg4jryaqlzmx44mfr87nds83margfa09ggd92sy0rudl6r79sat4rxqml5yfdhmm7yk9jc0ugzw7hgpdfxfzk'
curl --location --request POST $URI --header "$AUTH_TOKEN" --header 'Content-Type: application/json' --data-raw '{"query":"mutation lnInvoiceFeeProbe ($input: LnInvoiceFeeProbeInput!) {\n    lnInvoiceFeeProbe (input: $input) {\n        errors {\n            message\n            path\n        }\n        amount\n    }\n}","variables":{"input":{"paymentRequest":"'"$PAYMENT_REQUEST"'"}}}'
response
{
    "data": {
        "lnInvoiceFeeProbe": {
            "errors": [],
            "amount": 0
        }
    }
}
lnInvoicePaymentSend
query
PAYMENT_REQUEST='lntb50u1psc8xeppp5yryt4j8ve0pvyunrp3dr0l5tj0ss4hnkuxz52hldc9nz2njpe2fqdqqxqrrss9qy9qsqsp5xduj0a8u2c7mn959045wnu8xrv63vqye2d2zw3kllahdv47np6qsrzjqwfn3p9278ttzzpe0e00uhyxhned3j5d9acqak5emwfpflp8z2cng85uzyqqqdsqqqqqqqlgqqqqqeqqjqjwcuu47akd6qggafxy403zk9f67xh86huv6r0fkngvkuwrxuadv8dd3u5gfeurshh3q6jr5jvu05z7f63xz5ac8v4pk3tjfv46jt5dcprr9d4z'
curl --location --request POST $URI --header "$AUTH_TOKEN" --header 'Content-Type: application/json' --data-raw '{"query":"mutation lnInvoicePaymentSend ($input: LnInvoicePaymentInput!) {\n    lnInvoicePaymentSend (input: $input) {\n        errors {\n            message\n            path\n        }\n        status\n    }\n}","variables":{"input":{"paymentRequest":"'"$PAYMENT_REQUEST"'","memo":"'"$MEMO"'"}}}'
response
{
    "data": {
        "lnInvoicePaymentSend": {
            "errors": [],
            "status": "ALREADY_PAID"
        }
    }
}
If you use Postman, we have a collection you can import to test the API.
Download it here: Lightning Integration.postman_collection.json​
Queries
accountDefaultWallet
Response
Returns a PublicWallet!​
Arguments
Name
Description
username - Username!​
​
walletCurrency - WalletCurrency​
​
Example
Query
query accountDefaultWallet(
  $username: Username!,
  $walletCurrency: WalletCurrency
) {
  accountDefaultWallet(
    username: $username,
    walletCurrency: $walletCurrency
  ) {
    id
    walletCurrency
  }
}
Variables
{"username": Username, "walletCurrency": "BTC"}
Response
{"data": {"accountDefaultWallet": {"id": 4, "walletCurrency": "BTC"}}}
btcPrice
Example
Query
query btcPrice {
  btcPrice {
    base
    currencyUnit
    formattedAmount
    offset
  }
}
Response
{
  "data": {
    "btcPrice": {
      "base": 9007199254740991,
      "currencyUnit": "BTCSAT",
      "formattedAmount": "xyz789",
      "offset": 123
    }
  }
}
btcPriceList
Response
Returns [PricePoint]​
Arguments
Name
Description
range - PriceGraphRange!​
​
Example
Query
query btcPriceList($range: PriceGraphRange!) {
  btcPriceList(range: $range) {
    price {
      ...PriceFragment
    }
    timestamp
  }
}
Variables
{"range": "FIVE_YEARS"}
Response
{
  "data": {
    "btcPriceList": {
      "price": Price,
      "timestamp": 1592577642
    }
  }
}
businessMapMarkers
Response
Returns [MapMarker]​
Example
Query
query businessMapMarkers {
  businessMapMarkers {
    mapInfo {
      ...MapInfoFragment
    }
    username
  }
}
Response
{
  "data": {
    "businessMapMarkers": {
      "mapInfo": MapInfo,
      "username": Username
    }
  }
}
globals
Response
Returns a Globals​
Example
Query
query globals {
  globals {
    buildInformation {
      ...BuildInformationFragment
    }
    nodesIds
  }
}
Response
{
  "data": {
    "globals": {
      "buildInformation": BuildInformation,
      "nodesIds": ["abc123"]
    }
  }
}
me
Example
Query
query me {
  me {
    contactByUsername {
      ...UserContactFragment
    }
    contacts {
      ...UserContactFragment
    }
    createdAt
    defaultAccount {
      ...AccountFragment
    }
    id
    language
    phone
    quizQuestions {
      ...UserQuizQuestionFragment
    }
    twoFAEnabled
    username
  }
}
Response
{
  "data": {
    "me": {
      "contactByUsername": UserContact,
      "contacts": [UserContact],
      "createdAt": 1592577642,
      "defaultAccount": Account,
      "id": 4,
      "language": Language,
      "phone": Phone,
      "quizQuestions": [UserQuizQuestion],
      "twoFAEnabled": false,
      "username": Username
    }
  }
}
mobileVersions
Response
Returns [MobileVersions]​
Example
Query
query mobileVersions {
  mobileVersions {
    currentSupported
    minSupported
    platform
  }
}
Response
{
  "data": {
    "mobileVersions": {
      "currentSupported": 987,
      "minSupported": 123,
      "platform": "abc123"
    }
  }
}
onChainTxFee
Response
Returns an OnChainTxFee!​
Arguments
Name
Description
address - OnChainAddress!​
​
amount - SatAmount!​
​
targetConfirmations - TargetConfirmations​
Default = 1
walletId - WalletId!​
​
Example
Query
query onChainTxFee(
  $address: OnChainAddress!,
  $amount: SatAmount!,
  $targetConfirmations: TargetConfirmations,
  $walletId: WalletId!
) {
  onChainTxFee(
    address: $address,
    amount: $amount,
    targetConfirmations: $targetConfirmations,
    walletId: $walletId
  ) {
    amount
    targetConfirmations
  }
}
Variables
{
  "address": OnChainAddress,
  "amount": SatAmount,
  "targetConfirmations": 1,
  "walletId": WalletId
}
Response
{
  "data": {
    "onChainTxFee": {
      "amount": SatAmount,
      "targetConfirmations": TargetConfirmations
    }
  }
}
quizQuestions
Response
Returns [QuizQuestion]​
Example
Query
query quizQuestions {
  quizQuestions {
    earnAmount
    id
  }
}
Response
{
  "data": {
    "quizQuestions": {
      "earnAmount": SatAmount,
      "id": "4"
    }
  }
}
userDefaultWalletId
will be migrated to AccountDefaultWalletId
Response
Returns a WalletId!​
Arguments
Name
Description
username - Username!​
​
Example
Query
query userDefaultWalletId($username: Username!) {
  userDefaultWalletId(username: $username)
}
Variables
{"username": Username}
Response
{"data": {"userDefaultWalletId": WalletId}}
usernameAvailable
Response
Returns a Boolean​
Arguments
Name
Description
username - Username!​
​
Example
Query
query usernameAvailable($username: Username!) {
  usernameAvailable(username: $username)
}
Variables
{"username": Username}
Response
{"data": {"usernameAvailable": false}}
Mutations
accountUpdateDefaultWalletId
Response
Returns an AccountUpdateDefaultWalletIdPayload!​
Arguments
Name
Description
input - AccountUpdateDefaultWalletIdInput!​
​
Example
Query
mutation accountUpdateDefaultWalletId($input: AccountUpdateDefaultWalletIdInput!) {
  accountUpdateDefaultWalletId(input: $input) {
    account {
      ...ConsumerAccountFragment
    }
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"input": AccountUpdateDefaultWalletIdInput}
Response
{
  "data": {
    "accountUpdateDefaultWalletId": {
      "account": ConsumerAccount,
      "errors": [Error]
    }
  }
}
captchaCreateChallenge
Response
Returns a CaptchaCreateChallengePayload!​
Example
Query
mutation captchaCreateChallenge {
  captchaCreateChallenge {
    errors {
      ...ErrorFragment
    }
    result {
      ...CaptchaCreateChallengeResultFragment
    }
  }
}
Response
{
  "data": {
    "captchaCreateChallenge": {
      "errors": [Error],
      "result": CaptchaCreateChallengeResult
    }
  }
}
captchaRequestAuthCode
Response
Returns a SuccessPayload!​
Arguments
Name
Description
input - CaptchaRequestAuthCodeInput!​
​
Example
Query
mutation captchaRequestAuthCode($input: CaptchaRequestAuthCodeInput!) {
  captchaRequestAuthCode(input: $input) {
    errors {
      ...ErrorFragment
    }
    success
  }
}
Variables
{"input": CaptchaRequestAuthCodeInput}
Response
{
  "data": {
    "captchaRequestAuthCode": {
      "errors": [Error],
      "success": false
    }
  }
}
deviceNotificationTokenCreate
Response
Returns a SuccessPayload!​
Arguments
Name
Description
input - DeviceNotificationTokenCreateInput!​
​
Example
Query
mutation deviceNotificationTokenCreate($input: DeviceNotificationTokenCreateInput!) {
  deviceNotificationTokenCreate(input: $input) {
    errors {
      ...ErrorFragment
    }
    success
  }
}
Variables
{"input": DeviceNotificationTokenCreateInput}
Response
{
  "data": {
    "deviceNotificationTokenCreate": {
      "errors": [Error],
      "success": true
    }
  }
}
intraLedgerPaymentSend
Description
Actions a payment which is internal to the ledger e.g. it does not use onchain/lightning. Does not currently support payments to or from USD wallets. Returns payment status (success, failed, pending, already_paid).
Response
Returns a PaymentSendPayload!​
Arguments
Name
Description
input - IntraLedgerPaymentSendInput!​
​
Example
Query
mutation intraLedgerPaymentSend($input: IntraLedgerPaymentSendInput!) {
  intraLedgerPaymentSend(input: $input) {
    errors {
      ...ErrorFragment
    }
    status
  }
}
Variables
{"input": IntraLedgerPaymentSendInput}
Response
{
  "data": {
    "intraLedgerPaymentSend": {
      "errors": [Error],
      "status": "ALREADY_PAID"
    }
  }
}
lnInvoiceCreate
Description
Returns a lightning invoice for an associated wallet. When invoice is paid the value will be credited to a BTC wallet. Expires after 24 hours.
Response
Returns a LnInvoicePayload!​
Arguments
Name
Description
input - LnInvoiceCreateInput!​
​
Example
Query
mutation lnInvoiceCreate($input: LnInvoiceCreateInput!) {
  lnInvoiceCreate(input: $input) {
    errors {
      ...ErrorFragment
    }
    invoice {
      ...LnInvoiceFragment
    }
  }
}
Variables
{"input": LnInvoiceCreateInput}
Response
{
  "data": {
    "lnInvoiceCreate": {
      "errors": [Error],
      "invoice": LnInvoice
    }
  }
}
lnInvoiceCreateOnBehalfOfRecipient
Description
Returns a lightning invoice for an associated wallet. When invoice is paid the value will be credited to a BTC wallet. Expires after 24 hours.
Response
Returns a LnInvoicePayload!​
Arguments
Name
Description
input - LnInvoiceCreateOnBehalfOfRecipientInput!​
​
Example
Query
mutation lnInvoiceCreateOnBehalfOfRecipient($input: LnInvoiceCreateOnBehalfOfRecipientInput!) {
  lnInvoiceCreateOnBehalfOfRecipient(input: $input) {
    errors {
      ...ErrorFragment
    }
    invoice {
      ...LnInvoiceFragment
    }
  }
}
Variables
{"input": LnInvoiceCreateOnBehalfOfRecipientInput}
Response
{
  "data": {
    "lnInvoiceCreateOnBehalfOfRecipient": {
      "errors": [Error],
      "invoice": LnInvoice
    }
  }
}
lnInvoiceFeeProbe
Response
Returns a SatAmountPayload!​
Arguments
Name
Description
input - LnInvoiceFeeProbeInput!​
​
Example
Query
mutation lnInvoiceFeeProbe($input: LnInvoiceFeeProbeInput!) {
  lnInvoiceFeeProbe(input: $input) {
    amount
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"input": LnInvoiceFeeProbeInput}
Response
{
  "data": {
    "lnInvoiceFeeProbe": {
      "amount": SatAmount,
      "errors": [Error]
    }
  }
}
lnInvoicePaymentSend
Description
Pay a lightning invoice using a balance from a wallet which is owned by the account of the current user. Provided wallet can be USD or BTC and must have sufficient balance to cover amount in lightning invoice. Returns payment status (success, failed, pending, already_paid).
Response
Returns a PaymentSendPayload!​
Arguments
Name
Description
input - LnInvoicePaymentInput!​
​
Example
Query
mutation lnInvoicePaymentSend($input: LnInvoicePaymentInput!) {
  lnInvoicePaymentSend(input: $input) {
    errors {
      ...ErrorFragment
    }
    status
  }
}
Variables
{"input": LnInvoicePaymentInput}
Response
{
  "data": {
    "lnInvoicePaymentSend": {
      "errors": [Error],
      "status": "ALREADY_PAID"
    }
  }
}
lnNoAmountInvoiceCreate
Description
Returns a lightning invoice for an associated wallet. Can be used to receive any supported currency value (currently USD or BTC). Expires after 24 hours.
Response
Returns a LnNoAmountInvoicePayload!​
Arguments
Name
Description
input - LnNoAmountInvoiceCreateInput!​
​
Example
Query
mutation lnNoAmountInvoiceCreate($input: LnNoAmountInvoiceCreateInput!) {
  lnNoAmountInvoiceCreate(input: $input) {
    errors {
      ...ErrorFragment
    }
    invoice {
      ...LnNoAmountInvoiceFragment
    }
  }
}
Variables
{"input": LnNoAmountInvoiceCreateInput}
Response
{
  "data": {
    "lnNoAmountInvoiceCreate": {
      "errors": [Error],
      "invoice": LnNoAmountInvoice
    }
  }
}
lnNoAmountInvoiceCreateOnBehalfOfRecipient
Description
Returns a lightning invoice for an associated wallet. Can be used to receive any supported currency value (currently USD or BTC). Expires after 24 hours.
Response
Returns a LnNoAmountInvoicePayload!​
Arguments
Name
Description
input - LnNoAmountInvoiceCreateOnBehalfOfRecipientInput!​
​
Example
Query
mutation lnNoAmountInvoiceCreateOnBehalfOfRecipient($input: LnNoAmountInvoiceCreateOnBehalfOfRecipientInput!) {
  lnNoAmountInvoiceCreateOnBehalfOfRecipient(input: $input) {
    errors {
      ...ErrorFragment
    }
    invoice {
      ...LnNoAmountInvoiceFragment
    }
  }
}
Variables
{"input": LnNoAmountInvoiceCreateOnBehalfOfRecipientInput}
Response
{
  "data": {
    "lnNoAmountInvoiceCreateOnBehalfOfRecipient": {
      "errors": [Error],
      "invoice": LnNoAmountInvoice
    }
  }
}
lnNoAmountInvoiceFeeProbe
Response
Returns a SatAmountPayload!​
Arguments
Name
Description
input - LnNoAmountInvoiceFeeProbeInput!​
​
Example
Query
mutation lnNoAmountInvoiceFeeProbe($input: LnNoAmountInvoiceFeeProbeInput!) {
  lnNoAmountInvoiceFeeProbe(input: $input) {
    amount
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"input": LnNoAmountInvoiceFeeProbeInput}
Response
{
  "data": {
    "lnNoAmountInvoiceFeeProbe": {
      "amount": SatAmount,
      "errors": [Error]
    }
  }
}
lnNoAmountInvoicePaymentSend
Description
Pay a lightning invoice using a balance from a wallet which is owned by the account of the current user. Provided wallet must be BTC and must have sufficient balance to cover amount specified in mutation request. Returns payment status (success, failed, pending, already_paid).
Response
Returns a PaymentSendPayload!​
Arguments
Name
Description
input - LnNoAmountInvoicePaymentInput!​
​
Example
Query
mutation lnNoAmountInvoicePaymentSend($input: LnNoAmountInvoicePaymentInput!) {
  lnNoAmountInvoicePaymentSend(input: $input) {
    errors {
      ...ErrorFragment
    }
    status
  }
}
Variables
{"input": LnNoAmountInvoicePaymentInput}
Response
{
  "data": {
    "lnNoAmountInvoicePaymentSend": {
      "errors": [Error],
      "status": "ALREADY_PAID"
    }
  }
}
lnNoAmountUsdInvoiceFeeProbe
Response
Returns a CentAmountPayload!​
Arguments
Name
Description
input - LnNoAmountUsdInvoiceFeeProbeInput!​
​
Example
Query
mutation lnNoAmountUsdInvoiceFeeProbe($input: LnNoAmountUsdInvoiceFeeProbeInput!) {
  lnNoAmountUsdInvoiceFeeProbe(input: $input) {
    amount
    errors {
      ...ErrorFragment
    }
  }
}
Variables
{"input": LnNoAmountUsdInvoiceFeeProbeInput}
Response
{
  "data": {
    "lnNoAmountUsdInvoiceFeeProbe": {
      "amount": CentAmount,
      "errors": [Error]
    }
  }
}
lnNoAmountUsdInvoicePaymentSend
Description
Pay a lightning invoice using a balance from a wallet which is owned by the account of the current user. Provided wallet must be USD and have sufficient balance to cover amount specified in mutation request. Returns payment status (success, failed, pending, already_paid).
Name	Description
`address` - `OnChainAddress!`
`amount` - `SatAmount!`
`targetConfirmations` - `TargetConfirmations`	Default = `1`
`walletId` - `WalletId!`
Core API Reference

Galoy API Tutorial

Lightning Integration

Overview

Authentication

Curl requests

userRequestAuthCode

userLogin

lnInvoiceCreate

lnInvoiceFeeProbe

lnInvoicePaymentSend

Queries

`accountDefaultWallet`

`btcPrice`

`btcPriceList`

`businessMapMarkers`

`globals`

`me`

`mobileVersions`

`onChainTxFee`

`quizQuestions`

`userDefaultWalletId`

`usernameAvailable`

Mutations

`accountUpdateDefaultWalletId`

`captchaCreateChallenge`

`captchaRequestAuthCode`

`deviceNotificationTokenCreate`

`intraLedgerPaymentSend`

`lnInvoiceCreate`

`lnInvoiceCreateOnBehalfOfRecipient`

`lnInvoiceFeeProbe`

`lnInvoicePaymentSend`

`lnNoAmountInvoiceCreate`

`lnNoAmountInvoiceCreateOnBehalfOfRecipient`

`lnNoAmountInvoiceFeeProbe`

`lnNoAmountInvoicePaymentSend`

`lnNoAmountUsdInvoiceFeeProbe`

`lnNoAmountUsdInvoicePaymentSend`

Name	Description
`username` - `Username!`
`walletCurrency` - `WalletCurrency`