Authentication

Get JWT

Authenticate using signed payload to get a JWT for usage in other endpoints

There are multiple valid headers required to be sent as part of this request.

For onboarding examples, refer to go, java and python code in code-samples.

StarkNet Message Hash and Signature

Inspired by EIP-712, (a standard for hashing and signing typed structured data) the encoding of an off-chain message is defined as:

signed_data = Enc[PREFIX_MESSAGE, domain_separator, account, hash_struct(message)]

where:

• PREFIX_MESSAGE = "StarkNet Message"
• domain_separator is defined as the hash_struct of the StarkNetDomain struct:
  • Struct contains: name, chainId and version
  • chainId is can be obtained calling GET /system/config
• account is the StarkNet account address
• The message to be hashed is represented as a struct
  • hash_struct(message) = Enc[type_hash(MyStruct), Enc[param1], ..., Enc[paramN]]
  • where type_hash is defined as in EIP-712 (but using selector instead of keccak)
  • More details on StarkNet - Hash Functions

In case of more complex structure of object, you have to work in the spirit of EIP-712. This json structure has 4 mandatory items: types, primaryType, domain and message. These items are designed to be able to be an interface with a wallet. At sign request, the wallet will display:

• message will be displayed at the bottom of the wallet display, showing clearly (not in hex) the message to sign. Its structure has to be in accordance with the type listed in primaryType, defined in types.
• domain will be shown above the message. Its structure has to be in accordance with StarkNetDomain.

The predefined types that you can use :

• felt : for an integer on 251 bits.
• felt* : for an array of felt.
• string : for a shortString of 31 ASCII characters max.
• selector : for a name of a smart contract function.
• merkletree : for a Root of a Merkle tree, calculated with the provided data.

Specification details: Signing transactions and off-chain messages

Message Hash Sample Code

For a complete message_hash example, refer to python code in code-samples.

Examples:

{
  "paradex-signature-expiration": 1682364556,
  "paradex-starknet-account": "0x129f3dc1b8962d8a87abc692424c78fda963ade0e1cd17bf3d1c26f8d41ee7a",
  "paradex-starknet-signature": [
    "1381323390094460587764867648394252677239485992175346764030313478865763678671",
    "396490140510115262427678549757564216013606350105112805717359873954984880589"
  ],
  "paradex-timestamp": 1681759756
}

POSThttps://api.testnet.paradex.trade/v1/auth

Header parameters

Response

200400401

OK

Body

application/json

jwt_tokenstring

Authentication token

Example: "eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJhdCtKV1QiLCJleHAiOjE2ODE0NTI5MDcsImlhdCI6MTY4MTQ1MjYwNywiaXNzIjoiUGFyYWRleCBzdGFnaW5nIiwic3ViIjoiMHg0OTVkMmViNTIzNmExMmI4YjRhZDdkMzg0OWNlNmEyMDNjZTIxYzQzZjQ3M2MyNDhkZmQ1Y2U3MGQ5NDU0ZmEifQ.BPihIbGhnnsuPlReqC9x12JFXldpswg5EdA6tTiDQm-_UHaRz_8RfVBqWc2fPN6CzFsXTq7GowZu-2qMxPvZK_fGcxEhTp2k1r8MUxowlUIT4vPu2scCwrsyIujlCAwS"

Request

JavaScriptCurlPython

const response = await fetch('https://api.testnet.paradex.trade/v1/auth', {
    method: 'POST',
    headers: {
      "PARADEX-STARKNET-ACCOUNT": "text",
      "PARADEX-STARKNET-SIGNATURE": "text",
      "PARADEX-TIMESTAMP": "text"
    },
});
const data = await response.json();

Response

200400401

{
  "jwt_token": "eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJhdCtKV1QiLCJleHAiOjE2ODE0NTI5MDcsImlhdCI6MTY4MTQ1MjYwNywiaXNzIjoiUGFyYWRleCBzdGFnaW5nIiwic3ViIjoiMHg0OTVkMmViNTIzNmExMmI4YjRhZDdkMzg0OWNlNmEyMDNjZTIxYzQzZjQ3M2MyNDhkZmQ1Y2U3MGQ5NDU0ZmEifQ.BPihIbGhnnsuPlReqC9x12JFXldpswg5EdA6tTiDQm-_UHaRz_8RfVBqWc2fPN6CzFsXTq7GowZu-2qMxPvZK_fGcxEhTp2k1r8MUxowlUIT4vPu2scCwrsyIujlCAwS"
}

Onboarding

Onboarding verifies that the caller owns the StarkNet address and enters them into the database. This call is idempotent.

POSThttps://api.testnet.paradex.trade/v1/onboarding

Header parameters

Body

application/json

Onboarding user public_key

public_keystring

Public key of the user being onboarded.

Example: 1.74201940451046e+75

referral_codestring

Referral code of the user who referred the user being onboarded.

Example: "cryptofox8"

Response

200400401

An empty response

Request

JavaScriptCurlPython

const response = await fetch('https://api.testnet.paradex.trade/v1/onboarding', {
    method: 'POST',
    headers: {
      "PARADEX-ETHEREUM-ACCOUNT": "text",
      "PARADEX-STARKNET-ACCOUNT": "text",
      "PARADEX-STARKNET-SIGNATURE": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

400401

{
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}