Authentication#

If you use Agentic Wallet#

Agentic Wallet supports two authentication methods:

Email Authentication

API Key Authentication

Create or access your wallet with just an email — no developer account or API key required. Ideal for getting started quickly.

1
Talk to your Agent
plaintext
Log in to Agentic Wallet with email
2
Enter your email
plaintext
<email>
3
Enter the verification code
plaintext
<otp-code>

Note

Private keys are generated and stored in a TEE environment and are never exposed to anyone, including your Agent. Logging in again with the same email will restore your existing wallet — no need to recreate it.

The built-in sandbox keys are for testing only and may be subject to rate limits. For stable production usage, set up your own API credentials:

1
Go to OKX Developer Portal
Open the OKX Developer Portal.
2
Generate your API credentials
Generate your API Key, Secret Key, and Passphrase.

Have your Agent write the .env file

Tell your agent:

plaintext

Create a .env file with these variables: OKX_API_KEY, OKX_SECRET_KEY, and OKX_PASSPHRASE. Add .env to .gitignore.
And open it, tell me what to do next, and remind me to save after I filled out the passkeys.

Your agent will create the file and open it — paste your keys there.

Note

Never commit .env to git (add it to .gitignore) and never expose these credentials in logs, screenshots, or chat messages.

If you use Open API#

You can also authenticate using an API Key for Onchain OS Skills/Open API. You'll need to create a project and generate an API key in the developer management portal first. For detailed steps and resources, refer to here.

All API requests must include the following headers for authentication:

OK-ACCESS-KEY: API key
OK-ACCESS-TIMESTAMP: Request timestamp (UTC), in ISO format, e.g. 2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE: The passphrase specified when creating the API key
OK-ACCESS-SIGN: Signature

Signing steps:

1
Concatenate pre-hash string
Concatenate timestamp, method, requestPath, and body into a single string.
2
HMAC SHA256 signature
Sign the pre-hash string with the secret key (generated when creating the API key).
3
Base64 encode
Encode the signature result using Base64.

Example

For example, sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v6/dex/aggregator/swap', SecretKey)). The timestamp must match OK-ACCESS-TIMESTAMP. GET is the method (HTTP request method, all uppercase). /api/v6/dex/aggregator/swap is the requestPath. The body is empty — it can be omitted if there is no request body (typically for GET requests).

Note

The timestamp must not differ from the server time by more than 30 seconds. POST requests must include the raw request body in the signature calculation. The secret key is only visible at creation time — store it through a secure channel.

Postman Example

JavaScript Example

Postman is a popular API development and testing tool that allows developers to design, test, and document APIs. It provides a user-friendly graphical interface for sending HTTP requests to APIs.

If you haven't installed Postman yet, you can download it for free from the Postman website: https://www.postman.com/

Tip

This example requires a basic understanding of Postman.

1
Add Parameters
This typically applies to GET requests. If your request requires query parameters, you can add them as key-value pairs under the Params tab.
2
Set Headers
Under the Headers tab, add the following key-value pairs:
- OK-ACCESS-KEY
- OK-ACCESS-PASSPHRASE
3
Add Body
This typically applies to POST requests. If your request requires a request body, you can add it under the Body tab:
- Select raw and JSON from the dropdown menu
- Enter your request body in JSON format

Set Pre-request Script

Used to generate the required signature (OK-ACCESS-SIGN) and timestamp (OK-ACCESS-TIMESTAMP). Under the Pre-request Script tab, insert the script corresponding to your request type (GET requests exclude the request body; edit the secret key as needed).

GET request:

javascript

var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var sign = CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA256(
    isoString + method + path,
    pm.variables.replaceIn('{{secret_key}}')
  )
);

pm.request.headers.add({
  key: 'OK-ACCESS-SIGN',
  value: sign,
});

pm.request.headers.add({
  key: 'OK-ACCESS-TIMESTAMP',
  value: isoString,
});

POST request:

javascript

var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var bodyStr = pm.request.body.raw;
var sign = CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA256(
    isoString + method + path + bodyStr,
    pm.variables.replaceIn('{{secret_key}}')
  )
);

pm.request.headers.add({
  key: 'OK-ACCESS-SIGN',
  value: sign,
});

pm.request.headers.add({
  key: 'OK-ACCESS-TIMESTAMP',
  value: isoString,
});

To call the API via a JavaScript script, refer to the following code example:

javascript

const https = require('https');
const crypto = require('crypto');
const querystring = require('querystring');

// Define API credentials
const api_config = {
  api_key: '',
  secret_key: '',
  passphrase: '',
};

function preHash(timestamp, method, request_path, params) {
  // Create pre-sign string from parameters
  let query_string = '';
  if (method === 'GET' && params) {
    query_string = '?' + querystring.stringify(params);
  }
  if (method === 'POST' && params) {
    query_string = JSON.stringify(params);
  }
  return timestamp + method + request_path + query_string;
}

function sign(message, secret_key) {
  // Sign the pre-hash string using HMAC-SHA256
  const hmac = crypto.createHmac('sha256', secret_key);
  hmac.update(message);
  return hmac.digest('base64');
}

function createSignature(method, request_path, params) {
  // Get ISO 8601 formatted timestamp
  const timestamp = new Date().toISOString().slice(0, -5) + 'Z';
  // Generate signature
  const message = preHash(timestamp, method, request_path, params);
  const signature = sign(message, api_config['secret_key']);
  return { signature, timestamp };
}

function sendGetRequest(request_path, params) {
  // Generate signature
  const { signature, timestamp } = createSignature('GET', request_path, params);

  // Build request headers
  const headers = {
    'OK-ACCESS-KEY': api_config['api_key'],
    'OK-ACCESS-SIGN': signature,
    'OK-ACCESS-TIMESTAMP': timestamp,
    'OK-ACCESS-PASSPHRASE': api_config['passphrase'],
  };

  const options = {
    hostname: 'web3.okx.com',
    path: request_path + (params ? `?${querystring.stringify(params)}` : ''),
    method: 'GET',
    headers: headers,
  };

  const req = https.request(options, (res) => {
    let data = '';
    res.on('data', (chunk) => {
      data += chunk;
    });
    res.on('end', () => {
      console.log(data);
    });
  });

  req.end();
}

function sendPostRequest(request_path, params) {
  // Generate signature
  const { signature, timestamp } = createSignature(
    'POST',
    request_path,
    params
  );

  // Build request headers
  const headers = {
    'OK-ACCESS-KEY': api_config['api_key'],
    'OK-ACCESS-SIGN': signature,
    'OK-ACCESS-TIMESTAMP': timestamp,
    'OK-ACCESS-PASSPHRASE': api_config['passphrase'],
    'Content-Type': 'application/json',
  };

  const options = {
    hostname: 'web3.okx.com',
    path: request_path,
    method: 'POST',
    headers: headers,
  };

  const req = https.request(options, (res) => {
    let data = '';
    res.on('data', (chunk) => {
      data += chunk;
    });
    res.on('end', () => {
      console.log(data);
    });
  });

  if (params) {
    req.write(JSON.stringify(params));
  }

  req.end();
}

// GET request example
const getRequestPath = '/api/v6/dex/aggregator/quote';
const getParams = {
  chainIndex: 42161,
  amount: 1000000000000,
  toTokenAddress: '0xff970a61a04b1ca14834a43f5de4533ebddb5cc8',
  fromTokenAddress: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
};
sendGetRequest(getRequestPath, getParams);

// POST request example
const postRequestPath = '/api/v5/mktplace/nft/ordinals/listings';
const postParams = {
  slug: 'sats',
};
sendPostRequest(postRequestPath, postParams);

Table of contents

If you use Agentic Wallet

If you use Open API