テーマ

Support

Change Log

Authentication#

If you use Agentic Wallet#

Email Authentication#

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

Step 1#

Tell your Agent:

plaintext

Log in to Agentic Wallet with email

Step 2#

Enter your email and wait for the verification code:

plaintext

<email>

Step 3#

Enter the verification code:

plaintext

<otp-code>

Once verified, the Agent will automatically create a wallet on first login:

plaintext

Wallet created successfully!
EVM Address:    <evm-address>
Solana Address: <solana-address>

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.

API Key Authentication#

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:

Go to the OKX Developer Portal.
Generate your API Key, Secret Key, and Passphrase.

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:

Step 1: Concatenate timestamp, method, requestPath, and body into a single string
Step 2: Sign the pre-hash string (result of Step 1) using HMAC SHA256 with the secret key (generated when creating the API key)
Step 3: Encode the signature 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#

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.

Add Parameters#

This typically applies to GET requests.
If your request requires query parameters, you can add them under the Params tab. Here you can add key-value pairs for query parameters.

Set Headers#

Under the Headers tab, add the following key-value pairs:

OK-ACCESS-KEY
OK-ACCESS-PASSPHRASE

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.
When generating the pre-hash string, 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,
});

JavaScript Example#

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