Rest API V1

Introduction

The trading API uses an API Key based authentication system to operate with accounts.

When it comes to managing your account API keys and other actions associated with your wallet, the API uses a JWT based system associated with your EVM wallet.

The API Keys works with a permission based system. In the trading API, you can delegate access to one of your subaccounts to an specific API key with an associated scope.

For the API spec, use https://gw.carbon.inc/api

JWT Authentication

Certain components of the trading API require the user to login with their wallet to manage API keys and account permissions.

To authenticate with your wallet in the API and get your JWT auth to be able to manage your API keys, the first step is to generate a typed data message.

Copy

export function generateIntentXJWTIssueMessage(
  account: Address,
  scopes: AllowedScopes[],
  expiration: AllowedExpiration
): RegisterTypedData {
  const message: RegisterTypedData = {
    domain: {
      name: "IntentX",
      version: "1",
    },
    message: {
      userAddress: account,
      scope: scopes,
      expiration: expiration,
      signatureExpiration: parseInt(((Date.now() + 1000 * 60 * 10) / 1000).toFixed(0)), // 10 minutes from now
    },
    primaryType: "Session",
    types: {
      Session: [
        { name: "userAddress", type: "address" },
        { name: "scope", type: "string[]" },
        { name: "expiration", type: "string" },
      ],
    },
  };

  return message;
}

Then, you'll have to sign with your wallet the generated message.

Copy

// Create wallet from private key
const wallet = new ethers.Wallet(privateKey);
const address = wallet.address;
​
// Generate typed data for JWT token
const typedData: RegisterTypedData = generateIntentXJWTIssueMessage(
address as 0x${string},
"frontendAuth", // Required scope for API key management
"30d"
);
​
// Sign typed data
const signature = await wallet.signTypedData(typedData.domain, typedData.types, typedData.message);

Finally, you can interact with the JWT issuer app:

Copy

const response = await axios.post<{ token?: string; message?: string }>(
  "https://app-authentication-bb6ukllqqa-ew.a.run.app/register",
  {
    message,
    signature,
  },
  {
    headers: {
      "Content-Type": "application/json",
    },
  }
);

Then, with the 'token' you have got in the response, you will be able to interact with the API keys management in the Trading API.

You are required to use the following header with your generated token

Copy

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9