Intents

Create transfer intent

Changed on

Create an intent to execute a token transfer via a wallet. The intent must be authorized by either the wallet owner or signers before it can be executed.

post/v1/intents/wallets/{wallet_id}/transfer

Request

  • Base URL
    https://api.privy.io
  • URL
    https://api.privy.io/v1/intents/wallets/{wallet_id}/transfer
  • Auth
    HTTP basic

Path parameters

wallet_idstring required

ID of the wallet.

Headers

privy-app-idstring required

ID of your Privy app.

privy-request-expirystring

Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.

Request body

amountstring

Amount as a decimal string in the token's standard unit (e.g. "1.5" for 1.5 USDC). For exact_input, the amount to send. For exact_output, the exact amount to receive. Takes precedence over source.amount when both are provided.

amount_type'exact_input' | 'exact_output'

Whether the amount refers to the input token or output token.

slippage_bpsinteger

Maximum allowed slippage in basis points (1 bps = 0.01%). Only applicable for cross-chain or cross-asset transfers; omit to use the provider default.

noncestring

Unique caller-generated nonce used to prevent replaying a signed wallet action request. Must be at least 24 characters (e.g. a cuid2 or UUID).

reference_idstring

Developer-provided identifier for this request. Must be unique per app.

Example request

{
  "amount": "10.5",
  "source": {
    "asset": "ousd",
    "amount": "10.5",
    "chain": "tempo"
  },
  "destination": {
    "address": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2"
  }
}

Response

Created transfer intent.

intent_idstring required

Unique ID for the intent

created_by_display_namestring required

Display name of the user who created the intent

created_by_idstring

ID of the user who created the intent. If undefined, the intent was created using the app secret

created_atnumber required

Unix timestamp when the intent was created

resource_idstring required

ID of the resource being modified (wallet_id, policy_id, etc)

status'pending' | 'processing' | 'executed' | 'failed' | 'expired' | 'rejected' | 'dismissed' required

Current status of an intent.

custom_expiryboolean required

Whether this intent has a custom expiry time set by the client. If false, the intent expires after a default duration.

expires_atnumber required

Unix timestamp when the intent expires

rejected_atnumber

Unix timestamp when the intent was rejected, present when status is 'rejected'

dismissed_atnumber

Unix timestamp when the intent was dismissed, present when status is 'dismissed'

dismissal_reasonstring

Human-readable reason for dismissal, present when status is 'dismissed'

intent_type'TRANSFER' required

Example response

{
  "request_details": {
    "body": {
      "amount": "10.5",
      "source": {
        "asset": "ousd",
        "amount": "10.5",
        "chain": "tempo"
      },
      "destination": {
        "address": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2"
      }
    }
  },
  "current_resource_data": {
    "id": "id2tptkqrxd39qo9j423etij",
    "address": "0xF1DBff66C993EE895C8cb176c30b07A559d76496",
    "display_name": "Treasury",
    "external_id": "my-order-123",
    "chain_type": "ethereum",
    "policy_ids": [],
    "additional_signers": [],
    "owner_id": "rkiz0ivz254drv1xw982v3jq",
    "parent_wallet_id": null,
    "entity": {
      "id": "jorpjo4rfxj62nx1itt8y1zt",
      "type": "user"
    },
    "created_at": 1741834854578,
    "exported_at": null,
    "imported_at": null,
    "archived_at": null
  },
  "action_result": {
    "response_body": {
      "steps": [
        {
          "gas_credits_charged": {
            "value": "100.00",
            "currency": "usd"
          }
        }
      ],
      "estimated_fees": [
        {
          "type": "relayer",
          "recipient": "0x1234567890abcdef1234567890abcdef12345678",
          "amount": "0.20"
        }
      ],
      "estimated_gas": {
        "base_amount": "100000000000000",
        "amount": "0.0001",
        "gas_asset": "ETH"
      },
      "fees": [
        {
          "type": "relayer",
          "recipient": "0x1234567890abcdef1234567890abcdef12345678",
          "amount": "0.20"
        }
      ],
      "gas": {
        "base_amount": "100000000000000",
        "amount": "0.0001",
        "gas_asset": "ETH"
      }
    }
  }
}

Changes

  • 527110c2c2f4Revision changes
    • breaking

      the response property /////// became nullable for the status

    • breaking

      the response property /////// became nullable for the status

    • breaking

      the response property /////// became nullable for the status

    • breaking

      the response property /////// became nullable for the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      response property allOf[subschema #2]/action_result/allOf[subschema #2]/response_body/steps/items/oneOf[subschema #1: EVMTransactionWalletActionStep]/gas_credits_charged_usd deprecated

    • info

      response property allOf[subschema #2]/action_result/allOf[subschema #2]/response_body/steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/gas_credits_charged_usd deprecated

    • info

      response property allOf[subschema #2]/action_result/allOf[subschema #2]/response_body/steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/gas_credits_charged_usd deprecated

    • info

      response property allOf[subschema #2]/action_result/allOf[subschema #2]/response_body/steps/items/oneOf[subschema #4: TVMTransactionWalletActionStep]/gas_credits_charged_usd deprecated

  • a77e516e7c57Revision changes
    • info

      added the optional property /////// to the response with the status