Smart Contract Interactions

Organizational Custody supports full-featured smart contract execution across EVM, NEAR, and Solana. This allows your organization to participate in DeFi, mint NFTs, and interact with any on-chain program.

1. Executing a Function

Use the contract-execution endpoint to send a state-changing transaction to a smart contract.

Endpoint: POST /v2/organization/transactions/contract-execution
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Example: EVM (Minting an NFT)

Code
{
  "idempotencyKey": "b3e...",
  "walletId": "<evm_wallet_id>",
  "contractAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
  "abiFunctionSignature": "mint(address,uint256)",
  "abiParameters": ["0x742d...", "1"]
}

Example: NEAR (Calling a Method)

Code
{
  "idempotencyKey": "c4f...",
  "walletId": "<near_wallet_id>",
  "contractAddress": "guestbook.near",
  "abiFunctionSignature": "add_message(text)",
  "abiParameters": ["Hello from Planbok!"]
}

2. Parameter Handling

Planbok handles the encoding of your parameters based on the abiFunctionSignature you provide.

• Positional Parameters: For functions like transfer(address,uint256), the order in abiParameters must match the signature.
• SOL/NEAR-Specific: In SOL and NEAR, parameters are passed as a JSON object internally. Use the method_name(param1,param2) format in the signature, and Planbok will map the positional array to the named JSON keys.

3. Trustless MPC Requirements

If your organization is in Trustless MPC mode, you must include the encryptedOrganizationSecret in the request body. This allows the MPC nodes to derive the signing key for the specific contract interaction in real-time.

Code
{
  ...
  "encryptedOrganizationSecret": "BASE64_CIPHERTEXT"
}

4. Execution vs. View Calls

• Execution: Uses this guide. Costs gas, requires signing, and changes blockchain state.
• View Calls: For read-only data (e.g., checking balanceOf), use the /v2/transactions/contract-view/call endpoint which does not require signing or an organization secret.

Next Steps

To sign off-chain data instead of transactions, see Signing Messages & Typed Data.