Understanding Intents

Intents are high-level abstractions for on-chain actions. Instead of constructing and managing low-level blockchain transactions, you describe what you want to achieve—the intent—and Okto handles all the technical complexity behind the scenes.

What are Intents on Okto?

Okto Intents are designed to simplify the developer experience by abstracting away the intricacies of blockchain interactions. Think of intents as a translation layer between your application's needs and blockchain complexity. When an intent is submitted, the Okto platform is responsible for:

• Transaction Assembly: Translating the high-level intent into a compliant on-chain transaction.
• Fee Optimization: Calculating and applying appropriate gas fees for reliable execution.
• State Management: Handling the entire lifecycle of the transaction, from submission to confirmation.
• Cross-Chain Execution: Orchestrating complex multi-step workflows for intents across different networks.
• Ensure Security: Validate all parameters and provide built-in safety mechanisms.

Key Benefits

Core Intent Types

Okto API V2 provides these Intent types:

The Role of the UserOperation in Intents

A common point of confusion for developers is the presence of a large UserOperation (UserOp) payload in the intent API requests. This payload is fundamental to Okto's architecture and is a direct consequence of our commitment to self-custody and decentralization through Account Abstraction (ERC-4337).

Why is a UserOp necessary?

Every Okto user is provisioned with a self-custodial smart contract wallet. All interactions with this wallet—such as transferring a token or calling a contract function—must be initiated via an on-chain transaction. In the ERC-4337 standard, these actions are encapsulated within a UserOperation.

The UserOp is a pseudo-transaction object that describes the action the user's smart wallet should perform. For a detailed breakdown of its structure and role in Account Abstraction, please refer to our guide on Understanding UserOps.

The API Workflow: Estimate & Execute

For most intents, the implementation follows a simple two-step process. This workflow is designed to abstract away the complexity of building and signing blockchain transactions.

1. Estimate the Intent

Call the estimate endpoint with your intent's high-level details. Okto returns a pre-populated UserOperation object and gas fee estimates.

Use this step to preview gas costs, handle cross-chain or complex transactions, or enable features like sponsorship.

2. Execute the Intent

To execute an intent, you submit the signed userOps object (from the estimate response or your own construction) to the execute endpoint. The response includes a jobId for tracking transaction status.

Intent Implementation Guides

Below are practical guides for implementing the available intents using the Estimate & Execute flow.

Token Transfer

Use this intent to transfer a specified amount of a fungible token.

API Endpoints:

• Estimate: /api/oc/v1/estimate
• Execute: /api/oc/v1/execute

The payload for the /estimate endpoint requires the type and a details object containing the transfer information.

{
  "type": "TOKEN_TRANSFER",
  "jobId": "<unique-uuid-v4>",
  "details": {
    "caip2Id": "eip155:80002",
    "tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "recipientWalletAddress": "0x15000a9E47E8527a7C4A02189e581F4D0Df589C3",
    "amount": "1000000"
  },
  ... // Other fields like gasDetails, paymasterData
}

Key details Fields:

• caip2Id: The network identifier (e.g., eip155:80002 for Polygon Amoy).
• tokenAddress: The contract address of the ERC-20 token. Leave this as an empty string ("") for native token.
• recipientWalletAddress: The destination address.
• amount: The quantity of the token to send, expressed in its lowest denomination (e.g., wei for ETH-like tokens).

NFT Transfer

Use this intent to transfer an ERC-721 or ERC-1155 non-fungible token.

API Endpoints:

• Estimate: /api/oc/v1/estimate
• Execute: /api/oc/v1/execute

The payload for the /estimate endpoint specifies the NFT to be transferred.

{
  "type": "NFT_TRANSFER",
  "jobId": "<unique-uuid-v4>",
  "details": {
    "caip2Id": "eip155:80002",
    "collectionAddress": "0x0b5ca10156a184201d93609fd7d1606c10d5da21",
    "nftId": "0",
    "recipientWalletAddress": "0x597F2Fd9E42b58dF047849Bb29E25377745fF0da",
    "nftType": "ERC721",
    "amount": "1"
  },
  ... // Other fields like gasDetails, paymasterData
}

Key details Fields:

• collectionAddress: The smart contract address of the NFT collection.
• nftId: The specific token ID of the NFT to transfer.
• nftType: Either "ERC721" or "ERC1155".
• amount: For ERC-721, this should always be "1". For ERC-1155, specify the quantity to transfer.

Swap Intent

This powerful intent enables seamless token-for-token exchanges, both within the same blockchain and across different networks. It abstracts away the complexities of decentralized exchanges (DEXs) and bridges.

API Endpoints:

• Estimate: /api/oc/v1/estimate
• Execute: /api/oc/v1/execute

The payload for the /estimate endpoint defines the parameters for the desired swap using JSON-RPC format.

{
  "method": "estimate",
  "jsonrpc": "2.0",
  "id": "<request-id>",
  "params": [
    {
      "type": "SWAP",
      "jobId": "<unique-uuid-v4>",
      "paymasterData": "<paymaster-data>",
      "gasDetails": {
        "maxFeePerGas": "",
        "maxPriorityFeePerGas": ""
      },
      "details": {
        "fromChainCaip2Id": "eip155:8453",
        "toChainCaip2Id": "eip155:137",
        "fromChainTokenAddress": "",
        "toChainTokenAddress": "0x...",
        "fromChainTokenAmount": "100000000",
        "slippage": "3",
        "sameChainFee": "0",
        "sameChainFeeCollector": "0x2c2505D0E21f32F38bCEBeca1C331ab4069bBCb9",
        "crossChainFee": "10",
        "crossChainFeeCollector": "0x2c2505D0E21f32F38bCEBeca1C331ab4069bBCb9"
      }
    }
  ]
}

Key details Fields:

• fromChainCaip2Id & toChainCaip2Id: Define the source and destination networks using CAIP-2 format. These can be the same for intra-chain swaps.
• fromChainTokenAddress & toChainTokenAddress: Contract addresses of the tokens involved. Use an empty string ("") for native assets.
• fromChainTokenAmount: The amount of the source token to be swapped, in its lowest denomination (e.g., wei for ETH).
• slippage: The maximum acceptable price change percentage (e.g., "3" for 3%).
• sameChainFee & crossChainFee: Fee amounts for same-chain and cross-chain operations respectively.
• sameChainFeeCollector & crossChainFeeCollector: Addresses that collect the respective fees.

Additional Optional Fields:

• minToTokenAmount: Minimum amount of destination tokens expected (calculated automatically if not provided).
• advancedSettings: Additional configuration options for the swap.

Raw Transaction

This advanced intent allows you to execute any custom transaction by interacting directly with a smart contract. It provides maximum flexibility for use cases not covered by other intents.

Required Parameters by Blockchain

The essential parameters you provide within the transactions array vary by blockchain architecture:

API Endpoints:

• Estimate: /api/oc/v1/estimate
• Execute: /api/oc/v1/execute

The payload requires a transactions array, where each object represents a single contract call.

{
  "type": "RAW_TRANSACTION",
  "jobId": "<unique-uuid-v4>",
  "details": {
    "caip2Id": "eip155:84532", // BASE_TESTNET
    "transactions": [
      {
        "to": "0x363653DE3f920Ec8710b1Fc01e24Df96Bf7fb15E",
        "from": "0xA8c1021b6322e5fF8e059295fa027A1380789037",
        "value": "0x0",
        "data": "0x6057361d0000000000000000000000000000000000000000000000000000000000000005"
      }
    ]
  },
  // Other fields like gasDetails, paymasterData
}

{
  "type": "RAW_TRANSACTION",
  "jobId": "<unique-uuid-v4>",
  "details": {
    "caip2Id": "aptos:testnet", // APTOS_TESTNET
    "transaction": {
      "function": "0x1::aptos_account::transfer",
      "typeArguments": [],
      "functionArguments": [
        "0x9ed7f8c95c5e2c3cb06dfbb48681b87401fabeb88b7d710db3720f7a2ca3fffc",
        "10000"
      ]
    }
  },
  // Other fields like gasDetails, paymasterData
}

{
  "type": "RAW_TRANSACTION",
  "jobId": "<unique-uuid-v4>",
  "details": {
    "caip2Id": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // SOLANA_DEVNET
    "transaction": {
      "instructions": [
        {
          "keys": [
            {
              "pubkey": "CEGakCfWiBEUsh1vENRjZz26SiiVCu88ySjSPbRN7rsh",
              "isSigner": true,
              "isWritable": true
            }
          ],
          "programId": "BTSdutYFqgaecPtnEcEefPUBsLUu6i2o1xsLrdfqKV4T",
          "data": [102, 232, 96, 233, 198, 89, 95, 116]
        }
      ],
      "signer": "CEGakCfWiBEUsh1vENRjZz26SiiVCu88ySjSPbRN7rsh"
    }
  },
  // Other fields like gasDetails, paymasterData
}