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

# Request signing

> Sign the exact request bytes with RSA-SHA256.

THE PROOF

# Sign bytes, not objects

The canonical signing input is:

```text theme={null}
v1.<timestamp>.<idempotency-id>.<HTTP-method>.<path>.<raw-body>
```

The prefix and body are UTF-8 bytes. For a GET with no body, `<raw-body>` is empty.

## Example POST

```text theme={null}
v1.1795300000.0f0e0d0c-0b0a-4908-8706-050403020100.POST./v1/ramp/store-uuid/banking/conversions/quote.{"fromCurrency":"USD","toCurrency":"NGN","amount":1000}
```

Sign that exact byte sequence with:

```text theme={null}
RSA-SHA256
PKCS#1 v1.5 padding
Base64 output
```

## Signing examples

The following examples use the same canonical request and show the common implementation languages.

```javascript Node.js theme={null}
import { createSign, randomUUID } from "node:crypto";
import fs from "node:fs";

const timestamp = Math.floor(Date.now() / 1000).toString();
const idempotency = randomUUID();
const method = "POST";
const path = "/v1/ramp/store-uuid/banking/conversions/quote";
const body = JSON.stringify({ fromCurrency: "USD", toCurrency: "NGN", amount: 1000 });
const canonical = `v1.${timestamp}.${idempotency}.${method}.${path}.${body}`;

const signer = createSign("RSA-SHA256");
signer.update(Buffer.from(canonical, "utf8"));
const signature = signer.sign(fs.readFileSync("./partner-private-key.pem"), "base64");

console.log({ timestamp, idempotency, signature });
```

```python Python theme={null}
import base64
import time
import uuid
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

timestamp = str(int(time.time()))
idempotency = str(uuid.uuid4())
method = "POST"
path = "/v1/ramp/store-uuid/banking/conversions/quote"
body = '{"fromCurrency":"USD","toCurrency":"NGN","amount":1000}'
canonical = f"v1.{timestamp}.{idempotency}.{method}.{path}.{body}".encode()

with open("./partner-private-key.pem", "rb") as key_file:
    private_key = serialization.load_pem_private_key(key_file.read(), password=None)

signature = base64.b64encode(
    private_key.sign(canonical, padding.PKCS1v15(), hashes.SHA256())
).decode()

print({"timestamp": timestamp, "idempotency": idempotency, "signature": signature})
```

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

import (
  "crypto"
  "crypto/rand"
  "crypto/rsa"
  "crypto/sha256"
  "crypto/x509"
  "encoding/base64"
  "encoding/pem"
  "fmt"
  "os"
  "time"
)

func main() {
  timestamp := fmt.Sprint(time.Now().Unix())
  idempotency := "replace-with-a-uuid"
  method := "POST"
  path := "/v1/ramp/store-uuid/banking/conversions/quote"
  body := `{"fromCurrency":"USD","toCurrency":"NGN","amount":1000}`
  canonical := []byte("v1." + timestamp + "." + idempotency + "." + method + "." + path + "." + body)

  pemBytes, _ := os.ReadFile("./partner-private-key.pem")
  block, _ := pem.Decode(pemBytes)
  key, _ := x509.ParsePKCS8PrivateKey(block.Bytes)
  digest := sha256.Sum256(canonical)
  signature, _ := rsa.SignPKCS1v15(rand.Reader, key.(*rsa.PrivateKey), crypto.SHA256, digest[:])

  fmt.Println(base64.StdEncoding.EncodeToString(signature))
}
```

```bash cURL theme={null}
timestamp="$(date +%s)"
idempotency="$(uuidgen | tr '[:upper:]' '[:lower:]')"
method="POST"
path="/v1/ramp/store-uuid/banking/conversions/quote"
body='{"fromCurrency":"USD","toCurrency":"NGN","amount":1000}'
canonical="v1.${timestamp}.${idempotency}.${method}.${path}.${body}"

signature="$(
  printf '%s' "$canonical" |
  openssl dgst -sha256 -sign ./partner-private-key.pem |
  openssl base64 -A
)"

curl "https://sandbox-api.bullring.finance${path}" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: prod-2026-02" \
  -H "X-Timestamp: ${timestamp}" \
  -H "X-Idempotency-Id: ${idempotency}" \
  -H "X-Digital-Signature: ${signature}" \
  --data "$body"
```

## Five-minute window

`X-Timestamp` is Unix time in seconds. Bullring accepts timestamps within five minutes of its clock, in either direction.

## Common mistakes

* Signing pretty JSON and sending compact JSON.
* Reordering JSON keys after signing.
* Including a query string in the canonical path when the request path differs.
* Reusing an idempotency ID for a different body.
* Sending the PEM key instead of the Base64 signature.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.