> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rampnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Access to APIs and Authentication

<Note>
  To start working with the Rampnow API, all clients must authenticate with valid keys provided in the Rampnow partner dashboard.
</Note>

An app token is a secure method of communication with our API. You can create an app token in the Partner Dashboard.

### Make requests

Authentication to Rampnow's API is performed via the custom HTTP header

| Property            | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| X-RAMPNOW-API-KEY   | an API Key that you generate in the Dashboard                             |
| X-RAMPNOW-SIGN      | a request signature in the HEX format. The signature is case insensitive. |
| X-RAMPNOW-TIMESTAMP | number of seconds since Unix Epoch in UTC.                                |

<Note>
  All API queries must be sent over HTTPS; plain HTTP will be refused. You must include your auth headers in all requests.
</Note>

### Sign requests

The value of the X-RAMPNOW-SIGN header is generated with the sha256 HMAC algorithm using a secret key (Secret key is generated in the merchant Dashboard as part of API key creation) on the bytes obtained by concatenating the following information:

<Info>
  All API requests must be signed using HMAC-SHA256 with your secret key. The signature ensures request authenticity and prevents tampering.
</Info>

### How Request Signing Works

Every API request requires two headers:

* `X-RAMPNOW-TIMESTAMP`: Current Unix timestamp
* `X-RAMPNOW-SIGN`: HMAC-SHA256 signature of your request

The signature is generated using your secret key (obtained from the merchant Dashboard during API key creation) on a message constructed from your request details.

### Signing Your Requests

<Steps>
  <Step title="Generate timestamp">
    Create a Unix timestamp value for the `X-RAMPNOW-TIMESTAMP` header.
  </Step>

  <Step title="Construct the message">
    Concatenate the following in order:

    1. Timestamp (as a string)
    2. HTTP method in uppercase (e.g., `GET`, `POST`)
    3. URI path with query parameters (e.g., `/api/partner/v1/ext/ramp_order/quote?srcCurrency=USD&dstCurrency=BTC`)
    4. Request body (if present, exactly as it will be sent)
  </Step>

  <Step title="Generate HMAC signature">
    Create an HMAC-SHA256 hash of the message using your secret key and set it as the `X-RAMPNOW-SIGN` header value.
  </Step>
</Steps>

<Warning>
  Your timestamp must be within 1 minute of the API server time. Ensure your server time is correctly synchronized.
</Warning>

### Examples of how you can sign your requests:

```python Python theme={null}
message = timestamp + 'POST' + url_path + body
hmac_message = hmac.digest(SECRET_KEY.encode(), message.encode(), hashlib.sha256)
```

### Code Examples

<CodeGroup>
  ```python Python theme={null}
  import time
  import base64
  import hashlib
  import hmac
  import json
  import requests

  SECRET_KEY = 'api-secret-key'
  API_KEY = 'api-key'
  base_url = 'https://api.rampnow.io' 
  path = '/api/partner/v1/ext/ramp_order/quote'

  # Prepare request data
  payload_data = {
      "orderType": "buy",  
      "srcAmount": "100.0",  
      "srcCurrency": "EUR",
      "srcChain": "fiat",  
      "dstChain": "ethereum", 
      "dstCurrency": "ETH", 
      "paymentMode": "card", 
      "apiKey": API_KEY,
      "walletAddress": "0x6782f3309EAE59BbffbE87d9f3d4117298861468", 
      "walletAddressTag": "",  
      "externalOrderId": "ajsdiauhdiqw7e78322wrnbjsahd", 
  }
  # Prepare request body
  payload = json.dumps(payload_data)

  # Generate timestamp
  timestamp = str(int(time.time()))
  # Construct message
  message = timestamp + 'POST' + path + payload
  # Generate HMAC signature
  signature = base64.b16encode(hmac.digest(SECRET_KEY.encode(), message.encode(), hashlib.sha256)).decode().lower()

  # Set headers
  headers = {
      'X-RAMPNOW-TIMESTAMP': timestamp,
      'X-RAMPNOW-SIGN': signature,
      'X-RAMPNOW-APIKEY': API_KEY,
      'Content-Type': 'application/json'
  }

  # Make request
  url = base_url + path
  response = requests.post(url, headers=headers, data=payload)
  print(response.status_code, response.text) 

  # Expected output for verification:
  # Timestamp: 1772080882
  # X-RAMPNOW-SIGN: d7c42027596c3987071cf68bcf792e04e6eb0be75dfc567c1c3ee229241a5943

  ```

  ```javascript Node.js theme={null}
  const crypto = require('crypto');
  const https = require('https');

  const SECRET_KEY = 'api-secret-key';
  const API_KEY = 'api-key';
  const baseUrl = 'https://api.rampnow.io';
  const path = '/api/partner/v1/ext/ramp_order/quote';

  // Prepare request data
  const payloadData = {
    orderType: "buy",
    srcAmount: "100.0",
    srcCurrency: "EUR",
    srcChain: "fiat",
    dstChain: "ethereum",
    dstCurrency: "ETH",
    paymentMode: "card",
    apiKey: API_KEY,
    walletAddress: "0x6782f3309EAE59BbffbE87d9f3d4117298861468",
    walletAddressTag: "",
    externalOrderId: "ajsdiauhdiqw7e78322wrnbjsahd",
  };

  // Prepare request body
  const payload = JSON.stringify(payloadData);

  // Generate timestamp
  const timestamp = String(Math.floor(Date.now() / 1000));

  // Construct message
  const message = timestamp + 'POST' + path + payload;

  // Generate HMAC signature
  const signature = crypto
    .createHmac('sha256', SECRET_KEY)
    .update(message)
    .digest('hex');

  // Set headers
  const headers = {
    'X-RAMPNOW-TIMESTAMP': timestamp,
    'X-RAMPNOW-SIGN': signature,
    'X-RAMPNOW-APIKEY': API_KEY,
    'Content-Type': 'application/json'
  };

  // Make request
  const url = new URL(baseUrl + path);
  const options = {
    hostname: url.hostname,
    port: 443,
    path: url.pathname,
    method: 'POST',
    headers: headers
  };

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

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(payload);
  req.end();

  // Expected output for verification:
  // Timestamp: 1772080882
  // X-RAMPNOW-SIGN: d7c42027596c3987071cf68bcf792e04e6eb0be75dfc567c1c3ee229241a5943

  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/hex"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  	"time"
  )

  func main() {
  	secretKey := "api-secret-key"
  	apiKey := "api-key"
  	baseURL := "https://api.rampnow.io"
  	path := "/api/partner/v1/ext/ramp_order/quote"

  	// Prepare request data
  	payloadData := map[string]any{
  		"orderType":       "buy",
  		"srcAmount":       "100.0",
  		"srcCurrency":     "EUR",
  		"srcChain":        "fiat",
  		"dstChain":        "ethereum",
  		"dstCurrency":     "ETH",
  		"paymentMode":     "card",
  		"apiKey":          apiKey,
  		"walletAddress":   "0x6782f3309EAE59BbffbE87d9f3d4117298861468",
  		"walletAddressTag": "",
  		"externalOrderId": "ajsdiauhdiqw7e78322wrnbjsahd",
  	}

  	// Prepare request body
  	payload, _ := json.Marshal(payloadData)

  	// Generate timestamp
  	timestamp := fmt.Sprintf("%d", time.Now().Unix())

  	// Construct message
  	message := timestamp + "POST" + path + string(payload)

  	// Generate HMAC signature
  	h := hmac.New(sha256.New, []byte(secretKey))
  	h.Write([]byte(message))
  	signature := hex.EncodeToString(h.Sum(nil))

  	// Set headers
  	req, _ := http.NewRequest("POST", baseURL+path, bytes.NewBuffer(payload))
  	req.Header.Set("X-RAMPNOW-TIMESTAMP", timestamp)
  	req.Header.Set("X-RAMPNOW-SIGN", signature)
  	req.Header.Set("X-RAMPNOW-APIKEY", apiKey)
  	req.Header.Set("Content-Type", "application/json")

  	// Make request
  	client := &http.Client{}
  	resp, _ := client.Do(req)
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(resp.StatusCode, string(body))
  }

  // Expected output for verification:
  // Timestamp: 1772080882
  // X-RAMPNOW-SIGN: d7c42027596c3987071cf68bcf792e04e6eb0be75dfc567c1c3ee229241a5943

  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.charset.StandardCharsets;
  import java.time.Instant;
  import java.util.HexFormat;
  import com.google.gson.Gson;
  import java.util.HashMap;
  import java.util.Map;

  public class RampnowAPI {
      public static void main(String[] args) throws Exception {
          String secretKey = "api-secret-key";
          String apiKey = "api-key";
          String baseUrl = "https://api.rampnow.io";
          String path = "/api/partner/v1/ext/ramp_order/quote";

          // Prepare request data
          Map<String, Object> payloadData = new HashMap<>();
          payloadData.put("orderType", "buy");
          payloadData.put("srcAmount", "100.0");
          payloadData.put("srcCurrency", "EUR");
          payloadData.put("srcChain", "fiat");
          payloadData.put("dstChain", "ethereum");
          payloadData.put("dstCurrency", "ETH");
          payloadData.put("paymentMode", "card");
          payloadData.put("apiKey", apiKey);
          payloadData.put("walletAddress", "0x6782f3309EAE59BbffbE87d9f3d4117298861468");
          payloadData.put("walletAddressTag", "");
          payloadData.put("externalOrderId", "ajsdiauhdiqw7e78322wrnbjsahd");

          // Prepare request body
          Gson gson = new Gson();
          String payload = gson.toJson(payloadData);

          // Generate timestamp
          String timestamp = String.valueOf(Instant.now().getEpochSecond());

          // Construct message
          String message = timestamp + "POST" + path + payload;

          // Generate HMAC signature
          Mac hmacSha256 = Mac.getInstance("HmacSHA256");
          SecretKeySpec secretKeySpec = new SecretKeySpec(
              secretKey.getBytes(StandardCharsets.UTF_8), 
              0, 
              secretKey.getBytes(StandardCharsets.UTF_8).length, 
              "HmacSHA256"
          );
          hmacSha256.init(secretKeySpec);
          byte[] hmacBytes = hmacSha256.doFinal(message.getBytes(StandardCharsets.UTF_8));
          String signature = HexFormat.of().formatHex(hmacBytes);

          // Create HTTP request
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(baseUrl + path))
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .header("X-RAMPNOW-TIMESTAMP", timestamp)
              .header("X-RAMPNOW-SIGN", signature)
              .header("X-RAMPNOW-APIKEY", apiKey)
              .header("Content-Type", "application/json")
              .build();

          // Make request
          HttpClient client = HttpClient.newHttpClient();
          HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
          
          System.out.println(response.statusCode() + " " + response.body());
      }
  }

  // Expected output for verification:
  // Timestamp: 1772080882
  // X-RAMPNOW-SIGN: d7c42027596c3987071cf68bcf792e04e6eb0be75dfc567c1c3ee229241a5943

  ```
</CodeGroup>

## Quick Reference

| Component    | Description                                             |
| ------------ | ------------------------------------------------------- |
| Secret Key   | Generated in merchant Dashboard during API key creation |
| Timestamp    | Unix timestamp, must be within 1 minute of server time  |
| HTTP Method  | Uppercase method name (GET, POST, etc.)                 |
| URI Path     | Full path with query parameters, starting with /        |
| Request Body | Exact body as sent (omit for GET requests)              |