Skip to main content

Developer Integration Guide

This guide walks developers through the full technical onboarding and integration process with CRYMBO Oracle. From publishing keys to triggering identity exchange and decrypting payloads, this walkthrough ensures seamless compliance integration.

Step 1: Complete Entity Onboarding​

  • Register via the CRYMBO Connect portal
  • Submit KYB documentation
  • Receive:
    • VASP ID
    • API credentials (Bearer token)
    • Master wallet address

Step 2: Publish Your Public Encryption Key​

  • Generate an X25519 key pair
  • Use the API or portal to publish your public key:

Request:

POST /api/keys/publish
Authorization: Bearer <token>
Content-Type: application/json

Body:

{
  "type": "X25519",
  "publicKey": "<base64-encoded-public-key>"
}

Step 3: Whitelist Operational Wallets​

Whitelisted wallets are the only addresses allowed to:

  • Send transactions
  • Interact with CRYMBO smart contracts
  • Request or publish encrypted PII

This ensures only VASP-owned wallets can participate. PII cannot be published for wallets that are not whitelisted.

Step 4: Register the Transaction​

Before making an identity request, you must register the transaction on-chain.

Smart Contract Call:

await crymboOracle.addTransaction(
  "polygon",         // Network name
  txHash,            // bytes32 transaction hash
  senderAddress,     // sender wallet
  receiverAddress    // receiver wallet
);

This step is required for requestPIIForTransaction to succeed.

Step 5: Trigger an Identity Request​

After registering the transaction, request identity verification:

await crymboOracle.requestPIIForTransaction(
  "polygon",
  ethers.encodeBytes32String(txHash),
  receiverAddress
);
  • Emits PIIRequested event
  • CRYMBO Oracle begins fetching PII

Step 6: Handle PII Pull Request (Sender Side)​

Expose the following backend endpoint:

POST /api/getPII
Authorization: Bearer <token>

Response:

{
  "encryptedKey": "...",
  "encryptedData": "...",
  "nonce": "...",
  "version": "1.0"
}

Step 7: (Optional) Push Encrypted PII​

If pushing instead of waiting for fetch:

POST /api/oracle/pushEncryptedPII
Authorization: Bearer <token>
Content-Type: application/json

Payload:

{
  "txHash": "...",
  "network": "polygon",
  "sender": "...",
  "receiver": "...",
  "encryptedKey": "...",
  "encryptedData": "...",
  "nonce": "..."
}

Step 8: Decrypt PII (Receiver Side)​

  • Listen for the PIIReceived event
  • Use private X25519 key to decrypt AES key
  • Use AES-GCM to decrypt the PII payload

Step 9: Monitor and Validate​

Track events on-chain and via API:

  • PIIRequested
  • PIIReceived
  • Validated

Use webhooks or polling to stay updated on transaction status.

🧪 For testnet access and sandbox credentials, contact: support@crymbo.io