GalaConnect API Beta (1.0.0)

Download OpenAPI specification:

Getting Started

GalaConnect offers a public API for programmatic use cases.

The base URI for all requests is https://api-galaswap.gala.com.

Authentication

Using the GalaConnect API requires a Gala account, which can be created at games.gala.com.

You must have your GalaChain wallet address, private key, and public key, in order to use the API.

Any write operation (creating swaps, accepting swaps, terminating swaps) via the API needs the following in order to be accepted by GalaChain:

  1. Your GalaChain wallet address as an X-Wallet-Address header.
  2. Your GalaChain public key as a signerPublicKey property in the request body, in base64 encoding.
  3. A signature for the request body signed with your private key, as a signature property in the request body.

Creating a Wallet

After creating an account on games.gala.com, visit account settings and follow the instructions to create a GalaChain "transfer code", which also initializes your GalaChain wallet. Keep your transfer code safe and secure. You will need it in the next step.

Getting your Private Key

Once you have a GalaChain wallet, visit account settings and download your GalaChain private key. Note that this link has a &plaintext query parameter to trigger it to download your private key in plaintext as an advanced user. This key is used to sign requests to the GalaConnect API. Your key will be downloaded in a text file which will also contain your GalaChain wallet address, which will look something like client|123456789abcdef012345678, and which you should provide in API requests as the X-Wallet-Address header.

Getting your Public Key

To get your public key, you can make the following request to the GalaConnect API, substituting your GalaChain wallet address for YOUR_WALLET_ADDRESS_HERE:

curl --request POST \
  --url https://api-galaswap.gala.com/galachain/api/asset/public-key-contract/GetPublicKey \
  --header 'Content-Type: application/json' \
  --data '{"user": "YOUR_WALLET_ADDRESS_HERE"}'

Your public key will be returned as a base64 encoded string in the response body. It will look something like Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY. For any request that requires a signature, you must include your public key in the request body as a signerPublicKey property.

Request Signing

Any request to the GalaConnect API that executes a write operation (creating swaps, accepting swaps, terminating swaps) must be signed using your GalaChain private key with a secp256k1 signature.

To calculate the signature for a request, first recursively order the properties of the request body alphabetically by name. Then, stringify the object to a minimal JSON string. Use your private key to calculate the signature on the keccak256 hash of the stringified object. The signature must be normalized such that it's less than or equal to half of the secp256k1 curve's order n. Provide the signature in the request body as a property named "signature".

Here is TypeScript code that demonstrates how to correctly implement signing in Node.js:

import stringify from 'json-stringify-deterministic';
import ellipticPkg from 'elliptic';
import jsSha3Pkg from 'js-sha3';
import BN from 'bn.js';

const { keccak256 } = jsSha3Pkg;
const { ec: EC } = ellipticPkg;
const ecSecp256k1 = new EC('secp256k1');

export function signObject<TInputType extends object>(
  obj: TInputType,
  privateKey: string
): TInputType & { signature: string } {
  const toSign = { ...obj };

  if ('signature' in toSign) {
    delete toSign.signature;
  }

  const stringToSign = stringify(toSign);
  const stringToSignBuffer = Buffer.from(stringToSign);

  const keccak256Hash = Buffer.from(keccak256.digest(stringToSignBuffer));
  const privateKeyBuffer = Buffer.from(privateKey.replace(/^0x/, ''), 'hex');

  const signature = ecSecp256k1.sign(keccak256Hash, privateKeyBuffer);

  // Normalize the signature if it's greater than half of order n
  if (signature.s.cmp(ecSecp256k1.curve.n.shrn(1)) > 0) {
    const curveN = ecSecp256k1.curve.n;
    const newS = new BN(curveN).sub(signature.s);
    const newRecoverParam = signature.recoveryParam != null ? 1 - signature.recoveryParam : null;
    signature.s = newS;
    signature.recoveryParam = newRecoverParam;
  }

  const signatureString = Buffer.from(signature.toDER()).toString('base64');

  return {
    ...toSign,
    signature: signatureString,
  };
}

For example, if your private key were 0x0000000000000000000000000000000000000000000000000000000000000001, then a request body with the following content:

{
  "gala": "swap",
  "is": "a",
  "decentralized": "exchange",
  "on": "galachain",
  "uniqueKey": "galaconnect-operation-dcdb4974-328b-440b-837d-ed53d80e60dd",
  "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY"
}

Would have the signature MEQCIExBcdA40VmP3a/efnM6J3E/VyN3HgTTXXXsMVPsc3sWAiBIxFesuT74Ge2PWoyrmIcual4UZGO8D8GgNDor93d26Q==, and the operation would be sent in the request body to the GalaConnect API as follows:

{
  "gala": "swap",
  "is": "a",
  "decentralized": "exchange",
  "on": "galachain",
  "uniqueKey": "galaconnect-operation-dcdb4974-328b-440b-837d-ed53d80e60dd",
  "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  "signature": "MEQCIExBcdA40VmP3a/efnM6J3E/VyN3HgTTXXXsMVPsc3sWAiBIxFesuT74Ge2PWoyrmIcual4UZGO8D8GgNDor93d26Q=="
}

Unique Key

All write operations require a uniqueKey in the request body, as shown in the example above. The uniqueKey should be prefixed with galaconnect-operation-. The rest is up to you, but must be globally unique. Using a UUID is a good choice. This key is used to prevent replay attacks and potential repeat submission of operations in the case of retries. GalaChain will not permit two transactions with the same uniqueKey to commit to the chain.

Headless Wallet

Instead of creating a full Gala platform account on games.gala.com, it is also possible to create a "headless" wallet via the GalaConnect API if you prefer, by using the CreateHeadlessWallet endpoint. You must provide a public key for the new wallet (unlike elsewhere in the API, you must provide the public key here in lowercase hexadecimal encoding, preceded by 0x).

To generate an address and keys for your new headless wallet, the following JavaScript code using the ethers library in Node.js will work:

const ethers = require('ethers');
const newWallet = ethers.Wallet.createRandom();
console.log('Public key:', newWallet.publicKey);
console.log('Private key:', newWallet.privateKey);
console.log('X-Wallet-Address', `eth|${newWallet.address.replace('0x', '')}`);

Be sure to keep your private key safe and secure as it cannot be recovered if lost.

Creating a headless wallet is effectively the same as connecting a Web3 wallet to the GalaConnect website client, and you can use headless wallets and Web3 wallets interchangeably with both the GalaConnect API and website client.

Uses

Swaps on GalaChain have a concept of uses, representing a division of the swap into discrete units that can be accepted separately. For example, a swap may offer 1000 $GALA for 2000 $SILK with five uses. When accepting this swap via the BatchFillTokenSwap endpoint, you may choose to use between one and five of those uses. If you choose to use all five uses, then you will receive 5000 $GALA in exchange for 10000 $SILK. If you choose to use only two uses, then you will receive 2000 $GALA in exchange for 4000 $SILK.

A swap remains active on GalaConnect until all of its uses have been accepted (or its creator terminates it). If a swap has already had two of its five uses accepted, then you can only accept up to the remaining three uses (which would be 3000 $GALA for 6000 $SILK in this case). You can determine how many uses of a swap have already been used by checking the usesSpent property returned from the FetchAvailableTokenSwaps endpoint.

When creating swaps via the API, it's best to create swaps with tiny quantity and huge number of uses. This makes your swap more flexible for swappers who may have a very specific amount of tokens they want to swap. When swaps are created via the GalaConnect website client, the quantities and uses are automatically optimized for the swap creator, so swaps created via the website client will always have low quantity and high uses.

The GalaConnect website client uses TypeScript code similar to the following to automatically optimize quantity and uses:

import BigNumber from 'bignumber.js';

const greatestCommonDivisor = (a: BigNumber, b: BigNumber): BigNumber =>
  a.isZero() ? b : greatestCommonDivisor(b.mod(a), a);

export function calculateSwapQuantitiesAndUsesValues(
  givingTokenDecimals: number,
  receivingTokenDecimals: number,
  givingTokenAmount: BigNumber,
  receivingTokenAmount: BigNumber,
) {
  const givingTokenQuantumAmount = BigNumber(
    givingTokenAmount.toFixed(givingTokenDecimals, BigNumber.ROUND_FLOOR),
  ).multipliedBy(BigNumber(10).pow(givingTokenDecimals));

  const receivingTokenQuantumAmount = BigNumber(
    receivingTokenAmount.toFixed(receivingTokenDecimals, BigNumber.ROUND_FLOOR),
  ).multipliedBy(BigNumber(10).pow(receivingTokenDecimals));

  const gcd = greatestCommonDivisor(givingTokenQuantumAmount, receivingTokenQuantumAmount);

  const givingTokenQuantity = givingTokenQuantumAmount
    .dividedBy(gcd)
    .dividedBy(BigNumber(10).pow(givingTokenDecimals));

  const receivingTokenQuantity = receivingTokenQuantumAmount
    .dividedBy(gcd)
    .dividedBy(BigNumber(10).pow(receivingTokenDecimals));

  const uses = gcd;

  return {
    givingTokenQuantity,
    receivingTokenQuantity,
    uses,
  };
}

For example if we want to swap a total of 1000 $GALA for 2000 $SILK (both of which have 8 decimals places), then the inputs to this function are 8, 8, 1000, 2000 and the output is:

{
  "givingTokenQuantity": "0.00000001",
  "receivingTokenQuantity": "0.00000002",
  "uses": "100000000000"
}

If we create a new swap with these parameters, then swappers can choose exactly how much they want to swap, with such high granularity that they can effectively swap any amount of $SILK they want up to the total swap size of 2000.

Note that the ability to break down swaps with high granularity requires that the swap creator not have an excessively precise total quantity that they want to swap. For example if we call this function with parameters 8, 8, 1000.00000001, 2000.00000001 then we cannot break that down at all, and the output is:

{
  "givingTokenQuantity": "1000.00000001",
  "receivingTokenQuantity": "2000.00000001",
  "uses": "1"
}

It is advisable to round your total quantities to use no more than four decimal places less than the maximum number of decimal places supported by the tokens you are swapping. For example, use no more than four decimal places when creating swaps for tokens that support up to eight decimal places, such as $GALA and $SILK. This guarantees that any swap you create can have at least ten thousand uses.

GalaChain Fees

Some GalaChain operations have fees associated with them. To get the current GalaChain fees for any operation, make a request as you normally would, but add /fee to the end of the path. You should also omit the signature and uniqueKey fields from the request body.

The /fee routes are not explicitly listed in the route reference below, but the previously described logic applies to all routes. Note that the fee to create a project token is a separate concept. That fee is not a chaincode fee and is levied in addition to the chaincode fees returned by the /v1/CreateProjectToken/fee route (if any).

As an example, to get the GalaChain fees for creating a swap, make a POST request to https://api-galaswap.gala.com/v1/RequestTokenSwap/fee. Here is an example of what this endpoint will return:

{
  "fees": [
    {
      "type": "galachain_automatic",
      "operationDto": {
        "offered": [
          {
            "quantity": "10",
            "tokenInstance": {
              "collection": "SILK",
              "category": "Unit",
              "type": "none",
              "additionalKey": "none",
              "instance": "0"
            }
          }
        ],
        "wanted": [
          {
            "quantity": "20",
            "tokenInstance": {
              "collection": "GALA",
              "category": "Unit",
              "type": "none",
              "additionalKey": "none",
              "instance": "0"
            }
          }
        ],
        "uses": "1"
      },
      "operationName": "RequestTokenSwap",
      "galaChainMethod": "RequestTokenSwap",
      "channel": "asset",
      "fee": "1",
      "feeInGala": "1",
      "feeToken": "GALA|Unit|none|none"
    }
  ]
}

The fee amount in this example is 1 $GALA, as read from the feeInGala field. Some operations may return multiple fees, which you can sum together for the total fee. Fees are always in $GALA.

There are two types of fees and they must be treated quite differently:

galachain_automatic

You do not need to do anything special to pay this fee. It is automatically deducted from your wallet balance when you submit your operation and it commits to GalaChain.

galachain_cross_channel_authorization

This type of fee must be paid manually and is levied for certain operations on channels besides the asset channel. You will not encounter this type of fee if you only operate on tokens that are swappable on GalaConnect. However you may encounter this type of fee if you use the /galachain/ endpoints to operate on NFTs, which often exist on channels other than the asset channel.

To pay the feeInGala in such cases, you must make a request to the /v1/channels/{channel}/AuthorizeFee endpoint documented below. Making a request to this endpoint will burn $GALA on the asset channel, and give you a fee credit on the target channel. You can then carry out your operation on the target channel. You may also batch and pay this fee in advance if you choose to. For example if you know that you need to transfer ten NFTs and you know that each transfer will cost one $GALA, you may make a single request to /v1/channels/{channel}/AuthorizeFee to authorize a fee of ten $GALA, and then you can perform the ten transfers.

Rate Limiting

The GalaConnect API has a global rate limit of 20 requests per every 10 seconds. If you exceed the limit, you will receive a 429 Too Many Requests response. The response will contain a Retry-After header indicating the number of seconds you must wait before making another request. For example if you must wait 5 seconds before making another request, the API will send a 429 response containing a Retry-After header whose value is 5.

In addition, you should avoid performing write operations (such as creating swaps) concurrently, as concurrent transactions affecting the same wallet may result in serialization failures, which would be returned as a 409 Conflict response.

The rate limiting policy is subject to change, thus code that uses the API should be prepared for the possibility of being rate limited. If you need a higher rate limit, please contact support@gala.com.

Errors

The GalaConnect API returns two classes of errors:

GalaConnect Errors

GalaConnect errors are errors that occur in GalaConnect's application code, as opposed to GalaChain chaincode. GalaConnect errors will always be returned as an object with:

  1. An error property containing an error code, such as INVALID_BODY.
  2. An errorId property with a unique ID for the error. You should record and share this ID with Gala support if you need assistance with the error.

Errors may also contain additional properties with more specific information, such as request validation failure details.

GalaChain Errors

GalaChain errors are returned when GalaChain chaincode encounters an error, which is then bubbled up through the GalaConnect application and back to you. GalaChain errors will be returned as an object with:

  1. A message property containing a description of the error.
  2. An error property containing an object with more details about the error, including an ErrorKey property with a specific error code.
  3. An errorId property with a unique ID for the error. You should record and share this ID with Gala support if you need assistance with the error.

Undocumented Response Properties

Some endpoints may return additional properties that are not documented here. Such properties are not guaranteed to be stable and should not be relied upon in your application.

API Recipes

Let's look at example requests for some common operations. For all of these requests we are using this wallet:

  1. Wallet address: client|123456789abcdef012345678
  2. Public key: Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY
  3. Private key: 0x0000000000000000000000000000000000000000000000000000000000000001

This is not a real wallet, so making these requests verbatim will fail. You would need to use your own credentials in place of the above. You would also need to provide a different uniqueKey that is globally unique.

The signatures in the examples are however correct (using the private key shown above and the uniqueKey shown in the request body), so you can use them as a reference to help validate your signing code.

Fetch Available $GALA to $SILK Swaps

Let's get a list of swaps where we can trade our $GALA for another wallet's $SILK.

fetch('https://api-galaswap.gala.com/v1/FetchAvailableTokenSwaps', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    offeredTokenClass: {
      collection: 'GALA',
      category: 'Unit',
      type: 'none',
      additionalKey: 'none',
    },
    wantedTokenClass: {
      collection: 'SILK',
      category: 'Unit',
      type: 'none',
      additionalKey: 'none',
    },
  }),
});

Response:

{
  "results": [
    {
      "offeredTokenClass": "SILK|Unit|none|none",
      "wantedTokenClass": "GALA|Unit|none|none",
      "created": 1712230114698,
      "expires": 0,
      "offered": [
        {
          "quantity": "192",
          "tokenInstance": {
            "additionalKey": "none",
            "category": "Unit",
            "collection": "SILK",
            "instance": "0",
            "type": "none"
          }
        }
      ],
      "offeredBy": "client|222222222222222222222222",
      "swapRequestId": "\u0000GCTSR\u00001712230114698\u00004e4c85d5f313ff871d2d677ac72d52c8cfc748bdc821f9d4a3f57395eec9d6c9\u0000",
      "uses": "1",
      "usesSpent": "0",
      "wanted": [
        {
          "quantity": "68",
          "tokenInstance": {
            "additionalKey": "none",
            "category": "Unit",
            "collection": "GALA",
            "instance": "0",
            "type": "none"
          }
        }
      ]
    }
  ]
}

Accept a Swap

Let's accept the swap we found in the previous example. This request requires authentication.

fetch('https://api-galaswap.gala.com/v1/BatchFillTokenSwap', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Wallet-Address': 'client|123456789abcdef012345678',
  },
  body: JSON.stringify({
    swapDtos: [
      {
        swapRequestId:
          '\u0000GCTSR\u00001712230114698\u00004e4c85d5f313ff871d2d677ac72d52c8cfc748bdc821f9d4a3f57395eec9d6c9\u0000',
        uses: '1',
        expectedTokenSwap: {
          wanted: [
            {
              quantity: '68',
              tokenInstance: {
                additionalKey: 'none',
                category: 'Unit',
                collection: 'GALA',
                instance: '0',
                type: 'none',
              },
            },
          ],
          offered: [
            {
              quantity: '192',
              tokenInstance: {
                additionalKey: 'none',
                category: 'Unit',
                collection: 'SILK',
                instance: '0',
                type: 'none',
              },
            },
          ],
        },
      },
    ],
    uniqueKey: 'galaconnect-operation-1',
    signerPublicKey: 'Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY',
    signature:
      'MEQCIEtyGcJDz9ulqt5Uk+epQbcZWFkwxBVRuLO/wcg3oUhBAiAOPDHZF8h5Sb5oUt5z1AWNqUWJcFsQBkUMt7ReEIZ22w==',
  }),
});

Create a Swap

Let's create a swap where we offer 1000 $GALA for 2000 $SILK. This request requires authentication.

fetch('https://api-galaswap.gala.com/v1/RequestTokenSwap', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Wallet-Address': 'client|123456789abcdef012345678',
  },
  body: JSON.stringify({
    offered: [
      {
        quantity: '1000',
        tokenInstance: {
          collection: 'GALA',
          category: 'Unit',
          type: 'none',
          additionalKey: 'none',
          instance: '0',
        },
      },
    ],
    wanted: [
      {
        quantity: '2000',
        tokenInstance: {
          collection: 'SILK',
          category: 'Unit',
          type: 'none',
          additionalKey: 'none',
          instance: '0',
        },
      },
    ],
    uses: '1',
    uniqueKey: 'galaconnect-operation-1',
    signerPublicKey: 'Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY',
    signature:
      'MEUCIQDdwEEGoLF/2pZizVeAeQGl3wBALQw1Dbh/4R6QR3RTiQIgFEwt1K+GgzhGyh6vPyEt8XF24u0d1pCOz78ct3Yhk7k=',
  }),
});

Response:

{
  "Status": 1,
  "Data": {
    "created": 1712241257995,
    "expires": 0,
    "fillIds": [],
    "offered": [
      {
        "quantity": "1000",
        "tokenInstance": {
          "additionalKey": "none",
          "category": "Unit",
          "collection": "GALA",
          "instance": "0",
          "type": "none"
        }
      }
    ],
    "offeredBy": "client|123456789abcdef012345678",
    "swapRequestId": "\u0000GCTSR\u00001712241257995\u0000f096cfda086df84a8ee38980b2c14cc9785930bf66dcf3e0448d661127e369b7\u0000",
    "txid": "f096cfda086df84a8ee38980b2c14cc9785930bf66dcf3e0448d661127e369b7",
    "uses": "1",
    "usesSpent": "0",
    "wanted": [
      {
        "quantity": "2000",
        "tokenInstance": {
          "additionalKey": "none",
          "category": "Unit",
          "collection": "SILK",
          "instance": "0",
          "type": "none"
        }
      }
    ]
  }
}

Fetch the Fee to Terminate a Swap

Let's check if there is a fee to terminate (cancel) the swap that we just created.

fetch('https://api-galaswap.gala.com/v1/TerminateTokenSwap/fee', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Wallet-Address': 'client|123456789abcdef012345678',
  },
  body: JSON.stringify({
    swapRequestId:
      '\u0000GCTSR\u00001712241257995\u0000f096cfda086df84a8ee38980b2c14cc9785930bf66dcf3e0448d661127e369b7\u0000',
    signerPublicKey: 'Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY',
  }),
});

Response:

{
  "fees": [
    {
      "type": "galachain_automatic",
      "operationDto": {
        "swapRequestId": "GCTSR1710792378701ce0ec09292994e537eda883d8c40668a17641cb085d4c1fee8816ef41d91560e"
      },
      "operationName": "TerminateTokenSwap",
      "galaChainMethod": "TerminateTokenSwap",
      "channel": "asset",
      "fee": "0"
      "feeToken": "GALA|Unit|none|none"
    }
  ]
}

The fee is zero $GALA.

Terminate a Swap

Let's go ahead and terminate (cancel) the above swap that we just created.

fetch('https://api-galaswap.gala.com/v1/TerminateTokenSwap', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Wallet-Address': 'client|123456789abcdef012345678',
  },
  body: JSON.stringify({
    swapRequestId:
      '\u0000GCTSR\u00001712241257995\u0000f096cfda086df84a8ee38980b2c14cc9785930bf66dcf3e0448d661127e369b7\u0000',
    uniqueKey: 'galaconnect-operation-1',
    signerPublicKey: 'Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY',
    signature:
      'MEUCIQDqI9xkV2tocjBzpLMqI0WwFkVlieMaOt/nFIoSq9uoRgIgIcbGQ7kwXre2SDFOow62AoIc9Z9TfdZtiLE/cNEUDcI=',
  }),
});

API: GalaConnect Operations

Get Tokens

Get a list of tokens available on GalaConnect. By default, only "trending" tokens are returned. To get other tokens, use the searchprefix query parameter to search for them. Note that price information is not guaranteed, and the currentPrices property may be an empty object. Token prices are sourced from CoinGecko when possible. For project tokens (created by GalaConnect users) the price shown will be a historical average of the price that the token has been swapped at on GalaConnect. If there is no swap history yet for a project token, then its price will be assigned based on the amount of $GALA the creator burned to create it.

query Parameters
searchprefix
string

Perform a case-insensitive prefix search for tokens. The searched fields for each token are symbol, name, priceSymbol.

symbols
string

A comma-separated list of token symbols to fetch. If provided, only tokens with these symbols will be returned.

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ]
}

Get Swaps

Get a list of available swaps for the provided token pair. The wantedTokenClass should be the token that you want to receive, and the offeredTokenClass should be the token that you are willing to give in exchange. Up to 100 results are returned, ordered such that the ones with the best exchange rate (for you) come first. Note that in the response body, the perspective and meaning of "offered" and "wanted" is reversed compared to the request body. The "offered" field in the response is what the swap creator is offering, and the "wanted" field is what they want from you in exchange.

Request Body schema: application/json
required
required
object
required
object (TokenClass)

Responses

Request samples

Content type
application/json
{
  • "offeredTokenClass": {
    },
  • "wantedTokenClass": {
    }
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Accept Swaps

Accept one or more swaps that are being offered on GalaConnect.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "swapDtos": [
    ]
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Create Swap

Create a swap that other wallets will be able to see and accept.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
required
Array of objects (SwapOffered)
required
Array of objects (SwapWanted)
uses
required
string

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "offered": [
    ],
  • "wanted": [
    ],
  • "uses": "1"
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Cancel Swap

Cancel (terminate) a swap that you created.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
swapRequestId
required
string

The ID of the swap to cancel.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "swapRequestId": "\u0000GCTSR\u00001706318260580\u00009b5fca57bfcfe2b9bf9ecf8593ced274ff28bed85fb23eb6fb6f33978a343df2\u0000"
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Create Headless Wallet

Create a new headless wallet.

Request Body schema: application/json
required
publicKey
required
string

The public key for the new wallet in lowercase hex format, preceded by 0x.

Responses

Request samples

Content type
application/json
{
  • "publicKey": "0x02c5953291283d92392fad8d7ed2f77a976c35a472a5554dbe63c2269eacd8ff52"
}

Response samples

Content type
application/json
{
  • "walletAddress": "eth|4098698F65985F8C47DB8fBDdb47C90c36499a77",
  • "publicKey": "AsWVMpEoPZI5L62NftL3epdsNaRypVVNvmPCJp6s2P9S"
}

Authorize Cross-Channel Fee

Use this endpoint to pay a cross-channel fee. See the Fees section above for important information about cross-channel fees.

path Parameters
channel
required
string
Example: music

The target channel for the operation you need to pay a fee for. You should read this from the channel property in the response from the /fee endpoint for your desired operation.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
authority
required
string

This must be your wallet address and must match the key used to sign the request.

quantity
required
string

The quantity of $GALA to pay for the fee. This is a decimal number represented as a string, with no trailing zeroes after the decimal place.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "authority": "client|0123456789abcdef01234567",
  • "quantity": "100"
}

Response samples

Content type
application/json
{
  • "authorizeResponse": {
    },
  • "creditResponse": {
    }
}

Request to Bridge a Token

Create a request to bridge a token. This is the first of two requests you must make to bridge a token (the second is /v1/BridgeToken). Currently, it is only possible to bridge $MUSIC from the music channel to the asset channel, and vice versa. No other tokens may be bridged via the GalaConnect API at this time. Note that this is same as "wrapping" a token, as it is currently referred to in the GalaConnect web client.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
destinationChainId
required
number

The ID of the destination chain. This should be either 1 (when bridging to the asset channel) or 3 (when bridging to the music channel).

quantity
required
string
recipient
required
string

Your wallet address

required
object (TokenInstance)

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "destinationChainId": 1,
  • "quantity": "100",
  • "recipient": "client|0123456789abcdef01234567",
  • "tokenInstance": {
    }
}

Response samples

Content type
application/json
{
  • "Data": "\u0000GCTXR\u00003\u0000client|635f048ab243d7eb7f5ba044\u00001722632271929\u0000"
}

Bridge a Token

Bridge a token. This is the second of two calls you must make to bridge a token (the first is /v1/RequestBridgeToken).

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
bridgeFromChannel
required
string

The name of the channel you are bridging from. This should be either "asset" or "music".

bridgeRequestId
required
string

The ID of the bridge request you are fulfilling. This is the value returned by the /v1/RequestBridgeToken endpoint, which must be called first.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "bridgeFromChannel": "asset",
  • "bridgeRequestId": "\u0000GCTXR\u00003\u0000client|635f048ab243d7eb7f5ba044\u00001722632271929\u0000"
}

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Hash": "08ea70035f3dc4b7e1cb813e85333275a48abddf1d645b41910ce37fc4fd8022",
  • "Status": 1
}

API: GalaChain Operations

These operations are direct interactions with the GalaChain blockchain, with the GalaConnect API doing little more than proxying your request.

Get Balances

Use this endpoint to retrieve your wallet's balances on GalaChain. Some of your tokens may be locked (see the lockedHolds property in the response). Tokens are locked when they are currently being offered in an active swap, or may have been locked elsewhere on the Gala platform. Locked tokens cannot be used to create new swaps or to fill (accept) swaps, so you will generally want to subtract the quantity of locked tokens from your total overall quantity to decide how much you have available to use at the moment.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

Request Body schema: application/json
required
owner
required
string

Your wallet address.

Responses

Request samples

Content type
application/json
{
  • "owner": "client|0123456789abcdef01234567"
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Get Allowances

Use this endpoint to check your wallet's allowances on GalaChain. An allowance is a permission granted to you by another wallet, and allows you to perform operations that you wouldn't otherwise be able to do, such as locking or burning someone else's tokens.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

Request Body schema: application/json
required
grantedTo
required
string

The wallet address to fetch allowances for.

collection
string

A collection to filter by. Only allowances for tokens whose collection is this value will be returned.

category
string

A category to filter by. Only allowances for tokens whose category is this value will be returned. If you specify this, you MUST also specify collection.

type
string

A type to filter by. Only allowances for tokens whose type is this value will be returned. If you specify this, you MUST also specify category.

additionalKey
string

An additionalKey to filter by. Only allowances for tokens whose additionalKey is this value will be returned. If you specify this, you MUST also specify type.

instance
string

An instance to filter by. Only allowances for tokens whose instance is this value will be returned. If you specify this, you MUST also specify additionalKey.

Use0 (integer) or Lock1 (integer) or Spend2 (integer) or Transfer3 (integer) or Mint4 (integer) or Swap5 (integer) or Burn6 (integer) (AllowanceType)

The type of allowance. Some allowance types might not have any current use cases. The possible values are: 0 (Use), 1 (Lock), 2 (Spend), 3 (Transfer), 4 (Mint), 5 (Swap), 6 (Burn). If you specify this, you MUST also specify instance.

Responses

Request samples

Content type
application/json
{
  • "grantedTo": "client|0123456789abcdef01234567",
  • "collection": "GALA",
  • "category": "Unit",
  • "type": "none",
  • "additionalKey": "none",
  • "instance": "0",
  • "allowanceType": 0
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Get Swaps by User

Use this endpoint to fetch a list of swaps that you have created on GalaChain. This will include swaps that are currently active, and may also include swaps that are already expired or fully used.

Request Body schema: application/json
required
limit
number

The maximum number of swaps to fetch in this request.

bookmark
string

After making a request to this endpoint and receiving a response, you can use the nextPageBookMark property from the response to fetch the next page of results, by providing it here as the bookmark property in your next request.

user
required
string

Responses

Request samples

Content type
application/json
{
  • "limit": 100,
  • "bookmark": "string",
  • "user": "client|0123456789abcdef01234567"
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Get Mint Allowance Supply

Use this endpoint to fetch the mint allowance supply data for a given token.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

Request Body schema: application/json
required
collection
required
string
category
required
string
type
required
string
additionalKey
required
string

Responses

Request samples

Content type
application/json
{
  • "collection": "GALA",
  • "category": "Unit",
  • "type": "none",
  • "additionalKey": "none"
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Get Token Classes With Supply

Use this endpoint to fetch supply data for a given list of token classes.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

Request Body schema: application/json
required
required
Array of objects (TokenClass)

Responses

Request samples

Content type
application/json
{
  • "tokenClasses": [
    ]
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Get Token Mint Configurations

Use this endpoint to fetch a list of mint configurations for a given token. On mint actions, recipes can be configured to apply before or after the action.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

Request Body schema: application/json
required
collection
required
string
category
required
string
type
required
string
additionalKey
required
string
bookmark
required
string

After making a request to this endpoint and receiving a response, you can use the bookmark property from the response to fetch the next page of results, by providing it here as the bookmark property in your next request.

Responses

Request samples

Content type
application/json
{
  • "collection": "GALA",
  • "category": "Unit",
  • "type": "none",
  • "additionalKey": "none",
  • "bookmark": ""
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Get Public Key

Use this endpoint to get your GalaChain public key.

Request Body schema: application/json
required
user
required
string

The wallet address to fetch the public key for for.

Responses

Request samples

Content type
application/json
{
  • "user": "client|0123456789abcdef01234567"
}

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Transfer Tokens

Use this endpoint to transfer tokens from your wallet to another wallet on GalaChain.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
from
required
string

This should be your own wallet address.

to
required
string

The wallet address to send the tokens to.

required
object (TokenInstance)
quantity
required
string

The quantity of the token to send. This is a decimal number represented as a string. If you need to do arithmetic with this number, it is recommend to use a library like bignumber.js for arbitrary precision.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "from": "client|0123456789abcdef01234567",
  • "to": "client|0123456789abcdef01234567",
  • "tokenInstance": {
    },
  • "quantity": "100"
}

Mint Token With Allowance

Use this endpoint to mint tokens that you have created. You can only mint tokens that you have created via the project token feature (see /v1/CreateProjectToken) and only after they have been distributed to the node network.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
owner
required
string

The wallet address you want to mint to (doesn't have to be your own).

quantity
required
string

The quantity of the token to mint. This is a decimal number represented as a string.

required
object (TokenClass)
tokenInstance
required
string

This should always be the literal value "0".

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "owner": "client|0123456789abcdef01234567",
  • "quantity": "1000",
  • "tokenClass": {
    },
  • "tokenInstance": "0"
}

Mint Token

Use this endpoint to mint tokens that you have a mint allowance for.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
owner
required
string

The wallet address you want to mint to (doesn't have to be your own).

quantity
required
string

The quantity of the token to mint. This is a decimal number represented as a string.

required
object (TokenInstance)

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "owner": "client|0123456789abcdef01234567",
  • "quantity": "1000",
  • "tokenClass": {
    }
}

Batch Mint Token

Use this endpoint to perform multiple (up to 250) mint operations in one transaction. You must have a valid mint allowance for the tokens you want to mint.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
required
Array of objects [ 1 .. 250 ] items

Between 1 and 250 mint operations to perform.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "mintDtos": [
    ]
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Burn Tokens

Use this endpoint to burn GalaChain tokens.

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
required
Array of objects

The tokens to burn

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "tokenInstances": [
    ]
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

Grant Allowance

Use this endpoint to grant a mint allowance. You can only grant mint allowances for tokens that you are authority of (e.x. you created the token on GalaConnect).

path Parameters
channel
required
string
Example: asset

The home channel of the token you are operating on. In most cases (and in all cases for tokens that are swappable on GalaConnect) this will be asset.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
signature
required
string
signerPublicKey
required
string
uniqueKey
required
string
required
object (TokenInstance)
required
Array of objects [ 1 .. 250 ] items
allowanceType
required
number

This must be 4, which means the allowance type is "MintAllowance".

uses
required
string

This must equal 9007199254740991. This is the number of times an allowance can be used before it becomes unusable (even if the full quantity has not been used). This is a stringified integer.

Responses

Request samples

Content type
application/json
{
  • "signature": "MEUCIQCnXjZicvodRl0Hwyv6V1a3VU9WMsaVIxThVm0FTeuESwIgKDvv7z23QslMY6mEgSjzCK8A5LR7LV2WLCf+3CgPkPA=",
  • "signerPublicKey": "Anm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW+BeY",
  • "uniqueKey": "galaconnect-operation-0123456789",
  • "tokenInstance": {
    },
  • "quantities": [
    ],
  • "allowanceType": 4,
  • "uses": "9007199254740991"
}

Fetch Fee Balances

Use this endpoint to check your existing fee credit balance for fees on the specified channel. See the Fees section above for more info about fees on channels other than the asset channel.

path Parameters
channel
required
string
Example: music

The channel to fetch your fee balances for.

Request Body schema: application/json
required
owner
required
string

The wallet address to check fee balances for (typically your own).

bookmark
string

After making a request to this endpoint and receiving a response, you can use the nextPageBookmark property from the response to fetch the next page of results, by providing it here as the bookmark property in your next request.

Responses

Request samples

Content type
application/json
{
  • "owner": "client|0123456789abcdef01234567",
  • "bookmark": "string"
}

Response samples

Content type
application/json
{
  • "Data": [
    ]
}

GalaConnect Client Operations

These are operations that you should generally do via the GalaConnect website client. Nonetheless, they are documented here for completeness. These APIs are not likely to remain stable and you should not depend on them for production use.

Create Project Token

Use this endpoint to begin the process of creating a new token on GalaChain. Note that unlike most other operations, this one requires two separate signatures. You must sign the tokenCreationFeeBurn and burnAllowanceGrant properties in the request body.

header Parameters
X-Wallet-Address
required
string
Example: client|0123456789abcdef01234567

The wallet address of the wallet whose keys are being used to sign the request.

Request Body schema: application/json
required
required
object

A burn operation to burn $GALA as a fee for creating the new token.

required
object

A burn allowance grant that allows Gala to burn a limited amount of additional $GALA on your behalf in the future, to influence the new token's displayed price. You must provide this, but the quantity may be zero. We'll burn these tokens from your wallet after the node vote passes to create your new token (if it does).

required
object (NewProjectTokenDetails)

Responses

Request samples

Content type
application/json
{
  • "tokenCreationFeeBurn": {
    },
  • "burnAllowanceGrant": {
    },
  • "newToken": {
    }
}

Get Token Creation Jobs

Get a list of project tokens you have submitted for creation, including their status.

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

API: Node Operations

Get Founders Nodes Online Status

Get the online status of founders nodes for a specific user. Returns workload counts including founders nodes count.

query Parameters
userId
required
string
Example: userId=661563a60873b688d29edc57

The user ID for which to fetch nodes online status

Responses

Response samples

Content type
application/json
{
  • "userId": "661563a60873b688d29edc57",
  • "workloads": [
    ],
  • "foundersCount": 11,
  • "totalCount": 23
}