Create your API key

One API key does two jobs: it mints the tokens that authenticate your calls, and it signs your orders. You create it at app.truemarkets.co and keep the private half in a file.

1. Create the key

Sign in or create an account at app.truemarkets.co, then create an API key there. It's the same account you use in the app. Creating a key needs a passkey on your account. If you don't have one, the app asks you to register one first.

Your browser generates the key pair and registers the public half in two places. With your account, it lets you mint tokens. On your wallet, it lets you sign orders. The browser then downloads a JSON file with your key_id and the private key. The private key never leaves your machine.

Save the file and point TM_KEY_FILE at it.

The key file the app downloads

# The file the app downloaded, wherever you saved it
export TM_KEY_FILE="$HOME/.truemarkets/api-key.json"
cat $TM_KEY_FILE
# {
#   "key_id": "a1b2c3d4-…",
#   "private_key": { "kty": "EC", "crv": "P-256", … },
#   "algorithm": "ES256"
# }

Treat the file like a password

Anyone with the file can mint tokens as you and sign orders from your wallet. Keep it out of git and chat tools. If it leaks, revoke it at app.truemarkets.co and create a new one.

2. Mint a token

A token is what authenticates your API calls. To mint one, sign the string {key_id}.{timestamp} with the private key and post it to POST /v1/auth/api-key/token. The signature is ES256, with r and s concatenated and base64url-encoded, and the timestamp is Unix seconds within 30 seconds of our clock.

The response has an access token, which you send in Authorization: Bearer on every call, and a refresh token. Getting started, step 2 has the code.

3. Refresh the token

An access token lasts an hour, and expires_in is when it stops working. Before then, post the refresh token to get a new access token and refresh token. Refreshing needs no signature. Each refresh returns a new refresh token, so keep the latest one.

TypeScript

Get a new token pair with the refresh token

const minted = await post("/v1/auth/token/refresh", {
  refresh_token: refreshToken,
});

Python

Get a new token pair with the refresh token

minted = post("/v1/auth/token/refresh", {
    "refresh_token": refresh_token,
})

curl

Get a new token pair with the refresh token

curl -s -X POST https://api.truemarkets.co/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "'"$REFRESH_TOKEN"'"
  }'

Response200keep the new refresh_token

{
  "access_token": "eyJhbGciOi…",
  "refresh_token": "eyJhbGciOi…",
  "expires_in": "2026-10-01T19:11:27Z",
  "token_type": "Bearer"
}

Sign orders with the same key

The same key signs your orders, in a different format from the token challenge. How requests and signing work shows both.

Next: Getting started