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 step-by-step walkthrough ensures seamless compliance integration.

Step 1: Complete Entity Onboarding​

  • Register via 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 API or portal to publish the public key:
POST /api/keys/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "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 PII or publish encrypted PII

This ensures the VASP has ownership of the wallet addresses involved, as a signature from one of these wallets is required to prove control. PII can only be published for whitelisted wallets — preventing unauthorized disclosures for wallets not under the VASP's control.

Step 4: Trigger an Identity Request​

  • Call the smart contract function:
await crymboOracle.requestPIIForTransaction('polygon', ethers.encodeBytes32String(txHash), receiverAddress);
  • Emits PIIRequested event
  • CRYMBO Oracle begins fetching PII

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

  • Expose the following API:
POST /api/getPII
Authorization: Bearer <token>

Response Body:

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

Step 6: (Optional) Push Encrypted PII​

  • If pushing instead of waiting for a fetch:
POST /api/oracle/pushEncryptedPII
Authorization: Bearer <token>
Content-Type: application/json

Payload includes:

  • txHash
  • network
  • sender, receiver
  • encrypted data, key, nonce

Step 7: Decrypt PII (Receiver Side)​

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

Step 8: Monitor and Validate​

  • Watch events: PIIRequested, PIIReceived, Validated
  • Integrate with webhooks or poll API for status updates

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