End-to-End Field Encryption
You can encrypt specific fields of the request body with a public key issued by Octet and send them.
Octet decrypts them, restores the original fields, and runs the existing logic as is.
If the request body contains an encryptedFields field, the request is treated as using end-to-end field encryption.
Encryption can be done in the end user's app and relayed as is by the client server, or done directly by the client server. In both cases, the plain text is never exposed from the point of encryption to Octet.
TIP
This feature is optional. Calling withoutencryptedFieldsworks the same as before.
It can be used together with API payload encryption. Payload encryption is where the client server encrypts the entire request with a long-term symmetric key, whereas end-to-end field encryption encrypts only specific fields with a short-lived public key issued for each request.
Supported APIs and encryptable fields
It can be used with any API that receives an encryptable field in its body.
| Encryptable field | APIs that use it |
|---|---|
pin | Every API that receives a PIN, such as create child address, create/update child address PIN, withdrawal request, and NFT withdrawal request |
recoveryPin | Create child address, create/update/delete child address PIN |
If you encrypt a field outside the list above, the request is rejected (ERR_0459004). The value of an encrypted field must be a string. The target fields will be expanded in the future.
How it works
| Step | Actor | Action |
|---|---|---|
| 1 | Client server | Calls the Create end-to-end field encryption key API and receives { kid, publicKey, alg, enc, maxUseCount, expiresAt }. The key is valid for 5 minutes after issuance and can be used without a count limit within that time. |
| 2 | Encrypting party (end user app or client server) | JWE-encrypts the JSON { "pin": "...", "recoveryPin": "..." } with publicKey to produce a single string. If the end user app encrypts, the client server passes kid and publicKey to the app. |
| 3 | Client server | Sends the encryptedFields field in place of pin and recoveryPin in the existing API body. |
| 4 | Octet | Finds the private key by kid and decrypts. Restores the decrypted fields into the body and runs the existing logic. If the key has a use count limit, decrements the remaining count by one and discards the key immediately once it is used up. |
Encrypting fields end to end
1. Issue a key
The client server calls the Create end-to-end field encryption key API (POST /2.0/e2e-field-encryption/keys).
The body is optional; to limit the use count, send maxUseCount.
// Request body (optional)
{
"maxUseCount": 10
}
// Response
{
"kid": "7f3a2c9e-5b1d-4e8a-9f7d-2c5e8a1b4d6f",
"publicKey": {
"kty": "EC",
"crv": "P-256",
"x": "Vji7TZu5c-g8e7aH1CwaCRXrsaWNQCDOlc7rS6ZMcfg",
"y": "mI_nTSD-lRIad79h-ZvTHBaVgO0vMykRbocX7_QZ4DM",
"kid": "7f3a2c9e-5b1d-4e8a-9f7d-2c5e8a1b4d6f",
"alg": "ECDH-ES+A256KW",
"use": "enc"
},
"alg": "ECDH-ES+A256KW",
"enc": "A256GCM",
"maxUseCount": 10,
"expiresAt": "2026-09-10T10:05:00.000Z"
}
publicKeyis an EC P-256 public key in JWK (RFC 7517) format. Import it into your JOSE library as is.- The key is discarded once
expiresAt(5 minutes after issuance) passes. Within that time, it can be used for multiple requests without a count limit. - To limit the use count, also send
maxUseCount(an integer of 1 or more). Once the specified count is used up, the key is discarded immediately even if it has not yet expired. - The use count is decremented at the moment Octet retrieves the private key. A request rejected before the key is looked up because the
encryptedFieldsformat is invalid, such asERR_0459001, does not consume a use, but a request that fails at the decryption or validation stage (ERR_0459003toERR_0459005) or one with a wrong PIN does consume a use. - If the end user app encrypts, we recommend issuing the key when opening the PIN entry screen and passing it to the app.
2. Encrypt
Bundle the fields to encrypt into a JSON object and encrypt it with JWE (RFC 7516) compact serialization. The key names in the JSON are themselves the declaration of which fields were encrypted.
| Item | Value |
|---|---|
| Format | JWE compact serialization (header.encryptedKey.IV.ciphertext.tag) |
alg | ECDH-ES+A256KW (P-256) |
enc | A256GCM |
kid | The kid from the key issuance response (must be included in the protected header) |
| Plain text | A JSON object with string values only. Example: {"pin":"123456","recoveryPin":"654321"} |
You do not need to implement the cryptography yourself. Just pass the issued JWK and the plain text to a JOSE library.
The library creates an ephemeral EC key for each message and performs key agreement with the Octet public key (that ephemeral public key is automatically placed in the epk header), and encrypts the body with AES-256-GCM.
- TypeScript
- Java
// jose: 4.13 or higher (verified with 4.15.9; works in browsers, React Native, and Node.js)
import { CompactEncrypt, importJWK } from 'jose';
// publicKey from the key issuance API response
const publicKey = {
kty: 'EC',
crv: 'P-256',
x: 'Vji7TZu5c-g8e7aH1CwaCRXrsaWNQCDOlc7rS6ZMcfg',
y: 'mI_nTSD-lRIad79h-ZvTHBaVgO0vMykRbocX7_QZ4DM',
kid: '7f3a2c9e-5b1d-4e8a-9f7d-2c5e8a1b4d6f',
alg: 'ECDH-ES+A256KW',
use: 'enc',
};
// Include only the fields to encrypt (pin + recoveryPin for create child address, pin for withdrawal)
const fields = { pin: '123456', recoveryPin: '654321' };
const key = await importJWK(publicKey, 'ECDH-ES+A256KW');
const encryptedFields = await new CompactEncrypt(new TextEncoder().encode(JSON.stringify(fields)))
.setProtectedHeader({ alg: 'ECDH-ES+A256KW', enc: 'A256GCM', kid: publicKey.kid })
.encrypt(key);
// eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJraWQiOiI3ZjNhMmM5ZS0... (about 440 characters)
// nimbus-jose-jwt: 9.37.3 (JDK 17). Can be used the same way on Android.
import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.ECDHEncrypter;
import com.nimbusds.jose.jwk.ECKey;
// publicKey (JWK) JSON string from the key issuance API response
String publicKeyJson = "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"Vji7TZu5c-g8e7aH1CwaCRXrsaWNQCDOlc7rS6ZMcfg\",\"y\":\"mI_nTSD-lRIad79h-ZvTHBaVgO0vMykRbocX7_QZ4DM\",\"kid\":\"7f3a2c9e-5b1d-4e8a-9f7d-2c5e8a1b4d6f\",\"alg\":\"ECDH-ES+A256KW\",\"use\":\"enc\"}";
// Include only the fields to encrypt (pin + recoveryPin for create child address, pin for withdrawal)
String fieldsJson = "{\"pin\":\"123456\",\"recoveryPin\":\"654321\"}";
ECKey jwk = ECKey.parse(publicKeyJson);
JWEHeader header = new JWEHeader.Builder(JWEAlgorithm.ECDH_ES_A256KW, EncryptionMethod.A256GCM)
.keyID(jwk.getKeyID())
.build();
JWEObject jwe = new JWEObject(header, new Payload(fieldsJson));
jwe.encrypt(new ECDHEncrypter(jwk));
String encryptedFields = jwe.serialize();
// eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJt... (about 440 characters)
The same plain text produces a different result every time it is encrypted (an ephemeral key, a random AES key, and an IV are used for each message). The header field order differs between TypeScript and Java, so the output looks different, but Octet handles both identically.
3. Send to Octet
Call the API with the encryptedFields string placed in the existing API body instead of the encrypted fields. The endpoint and the remaining fields are the same as before.
// Create Child Address API Payload
// Existing
{
"offset": 1,
"pin": "123456",
"recoveryPin": "654321"
}
// With end-to-end field encryption
{
"offset": 1,
"encryptedFields": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJraWQiOiI..."
}
// Withdrawal request API Payload (with end-to-end field encryption)
{
"symbol": "ETH",
"requestId": "user1-amount0.001-symbolETH-202609031830",
"amount": "0.001",
"senderAddress": "0x55Bc4ba7A86A00C8A1A09C59DcC32eA2E7FAbCd4",
"receiverAddress": "0xee3c0f0AF227dA8DaccbF3Bc33bCf20f0a222aEF",
"encryptedUserKey": "rsa encrypted userkey",
"encryptedFields": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJraWQiOiI..."
}
- If you also send the encrypted fields (
pin,recoveryPin) in plain text, the request is rejected (ERR_0459005). encryptedUserKeyis a value the client encrypts directly with the Octet RSA public key and is not a target of end-to-end field encryption. Although the names are similar, the key and algorithm used are different, so send it as a separate field as before.- When using API payload encryption together, payload-encrypt the body that contains
encryptedFields, and compute the HMAC over that body as well. - Octet does not verify which request an
encryptedFieldsvalue is used in (it can be attached to any API request while the key is valid). If the end user app encrypts, the client server must use theencryptedFieldssent by the app only for the API call that user requested. - A key without a use count limit allows the same
encryptedFieldsto be sent multiple times during its validity period. This is convenient when you need to make several calls with the same PIN, such as creating a child address in each wallet, but for requests that must not be executed repeatedly, such as withdrawals, we recommend specifyingmaxUseCount: 1or discarding the key after use.
Retrieving a key
You can check the remaining use count and expiration time of an issued key. Call the Get key API (GET /2.0/e2e-field-encryption/keys/{kid}).
Retrieval does not consume a use.
// Response
{
"kid": "7f3a2c9e-5b1d-4e8a-9f7d-2c5e8a1b4d6f",
"maxUseCount": 10,
"remainingUseCount": 7,
"expiresAt": "2026-09-10T10:05:00.000Z"
}
- For a key without a use count limit, both
maxUseCountandremainingUseCountarenull. - A key that has expired or been discarded because its use count was exhausted cannot be retrieved (
ERR_0459006). - The public key is only returned at issuance, so it cannot be retrieved with this API.
Discarding a key
You can remove a key you have finished using before it expires. Call the Delete key API (DELETE /2.0/e2e-field-encryption/keys/{kid}).
// Response
{
"result": true
}
- When using a key without a use count limit, we recommend discarding it once you have completed all the necessary calls.
- For a key that has already expired or been discarded because its use count was exhausted, the response is
ERR_0459006.
Error codes
| Code | Situation | Action |
|---|---|---|
ERR_0459001 | The encryptedFields format is invalid. It is not JWE compact, alg/enc is not ECDH-ES+A256KW/A256GCM, or kid or epk is missing | Check the library settings (alg, enc, kid). |
ERR_0459002 | The key used for encryption cannot be found. The key has expired (5 minutes), its use count has been exhausted, or it has already been discarded | Issue a new key and encrypt again. |
ERR_0459003 | Decryption failed. It was encrypted with a different key, the value was tampered with, or the plain text is not a JSON object with string values only | Check that you encrypted with the issued publicKey and check the plain text format. |
ERR_0459004 | A field that cannot be encrypted is included | Include only the encryptable fields (pin, recoveryPin). |
ERR_0459005 | An encrypted field was also sent in plain text | Remove the plain text field from the body. |
ERR_0459006 | The key with that kid cannot be found in the get/delete key API | The key has expired, been exhausted, or already been discarded. Issue a new key if needed. |
When retrying after a failed request, a key without a use count limit can simply be used to encrypt again as long as it is still valid. However, since failed requests also consume uses, if a key with maxUseCount has been exhausted or you received ERR_0459002, you must issue a new key.
Testing
Because JWE uses random values every time, no fixed verification value ("this value must be produced") is provided. Verify by actually performing key issuance, encryption, and the API call in order in the test environment. If the implementation is wrong, you can identify the cause with the error codes above.