Class RestAuthenticatedClient

The RestAuthenticatedClient is used to make authenticated requests to the Katana Perps API. It includes methods that make requests on behalf of a specific wallet such as creating and cancelling orders.

  • The client requires the following properties to automatically handle authentication of requests:
  • Optionally, a sandbox option can be set to true in order to point to the Katana Perps Sandbox API.

Example

import { RestAuthenticatedClient } from '@katanaperps/katana-perps-sdk';

// Edit the values before for your environment
const authenticatedClient = new RestAuthenticatedClient({
  sandbox: false,
  apiKey: '1f7c4f52-4af7-4e1b-aa94-94fac8d931aa',
  apiSecret: 'axuh3ywgg854aq7m73oy6gnnpj5ar9a67szuw5lclbz77zqu0j',
  walletPrivateKey: '0x...'
});

See

Accessors

public

Constructor

constructor

Deposits & Withdrawals

getDeposit getDeposits withdraw transfer getWithdrawal getWithdrawals

Fills & Historical

getFill getFills getFundingPayments getHistoricalPnL

Orders

createOrder cancelOrders getOrder getOrders

Rewards & Payouts

getMarketMakerRewardsEpoch getMarketMakerRewardsEpochs authorizePayout getPayouts

Wallets & Positions

associateWallet getWallets getWalletList getDelegatedKeys authorizeDelegatedKey removeDelegatedKey getPositions setInitialMarginFractionOverride getInitialMarginFractionOverride

WebSocket

getWsToken

Other

calculateWithdrawalMaximumGasFee

Accessors

Readonly public

public: RestPublicClient

When creating an authenticated client, a katanaperps.RestPublicClient RestPublicClient is automatically created and can be used based on the config given for this client.

  • Can be utilized to fetch public data instead of creating both clients.
  • Used when fetching the katanaperps.KatanaPerpsExchange.exchangeContractAddress exchangeContractAddress and katanaperps.KatanaPerpsExchange.chainId chainId properties from the public client's getExchange method.

Example

import { RestAuthenticatedClient } from '@katanaperps/katana-perps-sdk';

// Edit the values before for your environment
const client = new RestAuthenticatedClient({
  sandbox: true,
  apiKey: '1f7c4f52-4af7-4e1b-aa94-94fac8d931aa',
  apiSecret: 'axuh3ywgg854aq7m73oy6gnnpj5ar9a67szuw5lclbz77zqu0j',
  walletPrivateKey: '0x...'
});

const wallets = await client.getWallets();

See

client katanaperps.RestPublicClient RestPublicClient

Constructor

constructor

Deposits & Withdrawals

getDeposit

getDeposits

withdraw

  • withdraw($params: RestRequestWithdrawFunds | RestRequestWithdrawFundsSDK, signer?: undefined | SignTypedData): Promise<KatanaPerpsWithdrawal>

  • Withdraw funds from the exchange.

    • Unlike deposits, withdrawals are initiated via this REST API endpoint.
    • Once the withdrawal is validated, Katana Perps automatically dispatches the resulting transaction to send funds to the wallet.

    Endpoint Parameters

    • HTTP Request: POST /v1/withdrawals
    • Endpoint Security: Trade
    • API Key Scope: Withdraw
    • Pagination: None

    Parameters

    Returns Promise<KatanaPerpsWithdrawal>

    • Returns an katanaperps.KatanaPerpsWithdrawal KatanaPerpsWithdrawal object providing the details of the withdrawal.

    Example

    // returns the max gas fee in USD you will accept for a withdrawal
    const maximumGasFee = await client.calculateWithdrawalMaximumGasFee({
     bridgeTarget: BridgeTarget.STARGATE_ETHEREUM,
     // 10% slippage alllowed (default)
     maximumSlippagePercent: '0.10000000'
    });

    // never pay more than $1 USD in gas fees to withdrawal
    if (Number(maximumGasFee) >= 1) {
     throw new Error('Too Much Gas cost to Withdraw! ${maximumGasFee} USD >= 1 USD!');
    }

    const withdrawal = await client.withdraw({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
      quantity: '100.00000000',
      maximumGasFee,
      bridgeTarget: BridgeTarget.STARGATE_ETHEREUM
    });

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestWithdrawFunds RestRequestWithdrawFunds
    • response katanaperps.RestResponseWithdrawFunds RestResponseWithdrawFunds
    • type katanaperps.KatanaPerpsWithdrawal KatanaPerpsWithdrawal
    • related calculateWithdrawalMaximumGasFee

transfer

  • transfer(params: RestRequestTransferFunds, signer?: undefined | SignTypedData): Promise<KatanaPerpsOutgoingTransfer>

  • Transfer collateral to another wallet without leaving the exchange.

    Endpoint Parameters

    • HTTP Request: POST /v1/transfers
    • Endpoint Security: Trade
    • API Key Scope: Withdraw

    Parameters

    Returns Promise<KatanaPerpsOutgoingTransfer>

    Example

    const transfer = await client.transfer({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
      targetWallet: '0x8bC1a9B2b6b1a17c8574c9E3fC5A2c2b1DfF9D1e',
      quantity: '100.00000000',
      maximumGasFee: '0.00000000',
    });

    See

    • request katanaperps.RestRequestTransferFunds RestRequestTransferFunds
    • response katanaperps.RestResponseTransferFunds RestResponseTransferFunds
    • type katanaperps.KatanaPerpsOutgoingTransfer KatanaPerpsOutgoingTransfer

getWithdrawal

getWithdrawals

Fills & Historical

getFill

getFills

getFundingPayments

  • getFundingPayments<R>(params: RestRequestGetFundingPayments): Promise<R>

  • Get Funding Payments for wallet matching katanaperps.KatanaPerpsFundingPayment KatanaPerpsFundingPayment

    Endpoint Parameters

    • HTTP Request: GET /v1/fundingPayments
    • Endpoint Security: User Data
    • API Key Scope: Read
    • Pagination: katanaperps.RestRequestPaginationWithFromId.start start, katanaperps.RestRequestPaginationWithFromId.end end, katanaperps.RestRequestPaginationWithFromId.limit limit

    Type Parameters

    Parameters

    Returns Promise<R>

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestGetFundingPayments RestRequestGetFundingPayments
    • response katanaperps.RestResponseGetFundingPayments RestResponseGetFundingPayments
    • type katanaperps.KatanaPerpsFundingPayment KatanaPerpsFundingPayment

getHistoricalPnL

Orders

createOrder

  • createOrder<T extends OrderType>(params: RestRequestOrder & {
        type: T;
    }, signer?: undefined | SignTypedData): Promise<RestResponseGetOrder>

  • Create and submit an order to the matching engine.

    • It is recommended to use the OrderType enum when creating your requests. This provides inline documentation and ensures accuracy of the values.
    • Check out the katanaperps.RestRequestOrder RestRequestOrder type for an overview of the various parameters needed for different order types.

    Endpoint Parameters

    • HTTP Request: POST /v1/orders
    • Endpoint Security: Trade
    • API Key Scope: Trade
    • Pagination: None

    Type Parameters

    Parameters

    • params: RestRequestOrder & {
          type: T;
      }
    • signer: undefined | SignTypedData = ...

    Returns Promise<RestResponseGetOrder>

    Example

    import { OrderType, OrderSide } from '@katanaperps/katana-perps-sdk';

    try {
      const order = await client.createOrder({
        // always use the enum and define it first so that
        // the type of this params object change to the
        // appropriate interface with completion hints in IDE!
        type: OrderType.market,
        // this object is now narrowed to
        // interface: RestRequestOrderTypeMarket
        side: OrderSide.buy,
        nonce: uuidv1(),
        wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
        market: 'ETH-USD',
        quantity: '10.00000000'
      });
    } catch(e) {
      // order placement failed with an unexpected error
      // you may use isAxiosError(e) for stronger typing here if desired
      if (e.response?.data?.code === 'INSUFFICIENT_FUNDS') {
         // handle insufficient funds errors
         console.log('Insufficient funds to create order');
      }
    }

    See

cancelOrders

  • cancelOrders(params: RestRequestCancelOrders, signer?: undefined | SignTypedData): Promise<RestResponseCancelOrders>

  • Cancel multiple matching orders using one of the following methods:

    • By katanaperps.RestRequestCancelOrdersByWallet.wallet wallet (params: katanaperps.RestRequestCancelOrdersByWallet RestRequestCancelOrdersByWallet)
    • By katanaperps.RestRequestCancelOrdersByMarket.wallet wallet & katanaperps.RestRequestCancelOrdersByMarket.market market (params: katanaperps.RestRequestCancelOrdersByMarket RestRequestCancelOrdersByMarket)
    • By katanaperps.RestRequestCancelOrdersByMarket.wallet wallet & katanaperps.RestRequestCancelOrdersByOrderIds.orderIds orderIds (params: katanaperps.RestRequestCancelOrdersByOrderIds RestRequestCancelOrdersByOrderIds)

    Endpoint Parameters

    • HTTP Request: DELETE /v1/orders
    • Endpoint Security: Trade
    • API Key Scope: Trade
    • Pagination: None

    Parameters

    Returns Promise<RestResponseCancelOrders>

    • Returns an array of cancelled orders matching katanaperps.KatanaPerpsCanceledOrder KatanaPerpsCanceledOrder

    Example

    const allOrders = client.cancelOrders({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
    });

    const ordersForMarket = client.cancelOrders({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
      market: 'ETH-USD'
    });

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestCancelOrders RestRequestCancelOrders
    • response katanaperps.RestResponseCancelOrders RestResponseCancelOrders
    • type katanaperps.KatanaPerpsCanceledOrder KatanaPerpsCanceledOrder
    • related cancelOrder client.cancelOrder

getOrder

getOrders

Rewards & Payouts

getMarketMakerRewardsEpoch

getMarketMakerRewardsEpochs

authorizePayout

  • authorizePayout(params: RestRequestAuthorizePayout): Promise<RestResponseAuthorizePayout>

  • Returns information about a payout program and the requested wallets earned/paid amounts for the program.

    • Includes the data required to authorize a payout using the distribute function of the escrow contract.
    • Throws an error if the katanaperps.KatanaPerpsPayoutProgram.quantityOwed quantityOwed is 0

    Endpoint Parameters

    • HTTP Request: POST /v1/payouts
    • Endpoint Security: User Data
    • API Key Scope: Read
    • Pagination: None

    Parameters

    Returns Promise<RestResponseAuthorizePayout>

    Example

    import { PayoutProgram } from '@katanaperps/katana-perps-sdk';

    // create client

    await client.authorizePayout({
     wallet: '0x...',
     nonce: uuidv1(),
     // use the PayoutProgram enum for inline auto completion
     program: PayoutProgram.tradingRewardsV2
    });

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestAuthorizePayout RestRequestAuthorizePayout
    • response katanaperps.RestResponseAuthorizePayout RestResponseAuthorizePayout
    • type katanaperps.KatanaPerpsPayoutProgramAuthorization KatanaPerpsPayoutProgramAuthorization

getPayouts

  • getPayouts(params: RestRequestGetPayouts): Promise<KatanaPerpsPayoutProgram>

  • Returns information about a payout program and the requested wallets earned/paid amounts for the program.

    Endpoint Parameters

    • HTTP Request: GET /v1/payouts
    • Endpoint Security: User Data
    • API Key Scope: Read
    • Pagination: None

    Parameters

    Returns Promise<KatanaPerpsPayoutProgram>

    Example

    import { PayoutProgram } from '@katanaperps/katana-perps-sdk';

    // create client

    await client.getPayouts({
     wallet: '0x...',
     nonce: uuidv1(),
     // use the PayoutProgram enum for inline auto completion
     program: PayoutProgram.tradingRewardsV2
    });

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestGetPayouts RestRequestGetPayouts
    • response katanaperps.RestResponseGetPayouts RestResponseGetPayouts
    • type katanaperps.KatanaPerpsPayoutProgram KatanaPerpsPayoutProgram

Wallets & Positions

associateWallet

  • associateWallet(params: RestRequestAssociateWallet, referralCode?: string, signer?: undefined | SignTypedData): Promise<KatanaPerpsWallet>

  • Associates a wallet with an API account, allowing access to private data such as fills. Associating a wallet with an API account is often the first step in interacting with private read endpoints.

    Endpoint Parameters

    • HTTP Request: POST /v1/wallets
    • Endpoint Security: Trade
    • API Key Scope: Read
    • Pagination: None

    Parameters

    Returns Promise<KatanaPerpsWallet>

    • Returns the katanaperps.KatanaPerpsWallet KatanaPerpsWallet which was associated by the request.

    Example

    const wallet = await client.associateWallet({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
    });

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestAssociateWallet RestRequestAssociateWallet
    • response katanaperps.RestResponseAssociateWallet RestResponseAssociateWallet
    • type katanaperps.KatanaPerpsWallet KatanaPerpsWallet

getWallets

getWalletList

getDelegatedKeys

authorizeDelegatedKey

removeDelegatedKey

getPositions

setInitialMarginFractionOverride

  • setInitialMarginFractionOverride<R>(params: RestRequestSetInitialMarginFractionOverride, signer?: undefined | SignTypedData): Promise<R>

  • Override minimum Initial Margin Fraction for wallet for a market

    Endpoint Parameters

    • HTTP Request: POST /v1/initialMarginFractionOverride
    • Endpoint Security: Trade
    • API Key Scope: Read
    • Pagination:

    Type Parameters

    • R = KatanaPerpsInitialMarginFractionOverride

    Parameters

    • params: RestRequestSetInitialMarginFractionOverride
    • signer: undefined | SignTypedData = ...

    Returns Promise<R>

    • Returns an katanaperps.KatanaPerpsInitialMarginFractionOverride KatanaPerpsInitialMarginFractionOverride object providing the details of the new setting.

getInitialMarginFractionOverride

WebSocket

getWsToken

  • getWsToken(params: RestRequestGetAuthenticationToken): Promise<string>

  • Returns a single-use authentication token as a string for access to katanaperps.SubscriptionNameAuthenticated authenticated subscriptions in the WebSocket API.

    Endpoint Parameters

    • HTTP Request: GET /v1/wsToken
    • Endpoint Security: User Data
    • API Key Scope: Read
    • Pagination: None

    Parameters

    Returns Promise<string>

    • Returns the katanaperps.KatanaPerpsWebSocketToken.token KatanaPerpsWebSocketToken.token string directly which you can use to authenticate with the WebSocket server.

    See

    • typedoc Reference Documentation
    • request katanaperps.RestRequestGetAuthenticationToken RestRequestGetAuthenticationToken
    • response katanaperps.RestResponseGetAuthenticationToken RestResponseGetAuthenticationToken

Other

calculateWithdrawalMaximumGasFee

  • calculateWithdrawalMaximumGasFee(__namedParameters: {
        bridgeTarget: BridgeTarget;
        maximumSlippagePercent: string;
    }): Promise<string>

  • A convenience method that helps capture the appropriate value for the withdraw method's katanaperps.RestRequestWithdrawFundsBase.maximumGasFee maximumGasFee parameter.

    • Calls publicClient.getGasFees and adds the defined maximumSlippagePercent to it.
    • User should then confirm the value is acceptable before calling withdraw method.
    • If gas were 0.05000000 and maximumSlippagePercent is 0.10000000 (10%) then result would be 0.05500000
    • The value is represented in USD.

    Parameters

    • __namedParameters: {
          bridgeTarget: BridgeTarget;
          maximumSlippagePercent: string;
      }
      • bridgeTarget: BridgeTarget

        The bridge target for the withdrawal of funds.

        • Utilize the BridgeTarget enum for convenience and auto-completion.
        • Automatically calculates the bridgeAdapterAddress & bridgeAdapterPayload parameters for the targeted network.

        See

        enum BridgeTarget

      • maximumSlippagePercent: string

        Maximum slippage percent in pips percent format (ex 0.10000000 for 10%)

        Example

        // 10%
        '0.10000000'

    Returns Promise<string>

    • A value indicating the max gas fee that should be allowed (in USD) based on the core gas fee with your maximumSlippagePercent added. This value should always be validated by your application before calling withdraw method with this as your katanaperps.RestRequestWithdrawFundsBase.maximumGasFee maximumGasFee parameter.

    Example

    // returns the max gas fee in USD you will accept for a withdrawal
    const maximumGasFee = await client.calculateWithdrawalMaximumGasFee({
     bridgeTarget: BridgeTarget.STARGATE_ETHEREUM,
     // 10% slippage alllowed (default)
     maximumSlippagePercent: '0.10000000'
    });

    // never pay more than $1 USD in gas fees to withdrawal
    if (Number(maximumGasFee) >= 1) {
     throw new Error('Too Much Gas cost to Withdraw! ${maximumGasFee} USD >= 1 USD!');
    }

    const withdrawal = await client.withdraw({
      nonce: uuidv1(),
      wallet: '0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d',
      quantity: '100.00000000',
      maximumGasFee,
      bridgeTarget: BridgeTarget.STARGATE_ETHEREUM
    });

    See

Settings

Member Visibility

Theme

On This Page

publicconstructorgetDepositgetDepositswithdrawtransfergetWithdrawalgetWithdrawalsgetFillgetFillsgetFundingPaymentsgetHistoricalPnLcreateOrdercancelOrdersgetOrdergetOrdersgetMarketMakerRewardsEpochgetMarketMakerRewardsEpochsauthorizePayoutgetPayoutsassociateWalletgetWalletsgetWalletListgetDelegatedKeysauthorizeDelegatedKeyremoveDelegatedKeygetPositionssetInitialMarginFractionOverridegetInitialMarginFractionOverridegetWsTokencalculateWithdrawalMaximumGasFee