> ## Documentation Index > Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt > Use this file to discover all available pages before exploring further. # Get an action > Get one action by id, with its unsigned transactions and current status. Poll this to track a multi-transaction action to `SUCCESS`. This is a proxy to the Yield.xyz Perps `GET /v1/actions/{id}` endpoint. Portal validates the upstream response against the schema documented here before returning it under `data`, and translates funding-chain `network` values to CAIP-2. If Yield.xyz changes the response shape, Portal returns a 500 with `id: INTEGRATION_RESPONSE_SCHEMA_DRIFT` instead of a partial response. Upstream reference: [Yield.xyz Perps API](https://docs.yield.xyz). ## OpenAPI ````yaml /openapi/client-api.yaml get /clients/me/integrations/yield-xyz-perps/actions/{id} openapi: 3.1.0 info: title: Portal Client API version: '3.0' description: > The Portal Client API provides endpoints for managing wallets, building transactions, and interacting with blockchain networks. All endpoints require authentication via a Client API Key or Client Session Token (CST) passed as a Bearer token. ## Base URL `https://api.portalhq.io/api/v3` ## Authentication Include your Client API Key or Client Session Token as a Bearer token in the `Authorization` header of every request. ## Chain ID Format Chain parameters use either friendly names (e.g. `ethereum`, `solana`) or CAIP-2 format (e.g. `eip155:1`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`). When using CAIP-2 format in URLs, ensure the colon is URI-encoded (`%3A`). servers: - url: https://api.portalhq.io/api/v3 description: Production security: - bearerAuth: [] tags: - name: Clients description: Core client management endpoints - name: Wallet description: >- Read wallet state — balances, NFTs, transaction history, capabilities, and transaction details - name: Transactions description: Build, broadcast, and evaluate blockchain transactions - name: Funding description: Fund wallets with testnet tokens - name: Wallet Shares description: Manage signing and backup share pairs - name: Delegations description: Manage token approvals, revocations, and delegated transfers - name: Session Keys description: Manage EIP-7702 session keys for smart accounts - name: 0x description: Token swap endpoints powered by the 0x protocol - name: Yield.xyz description: Yield opportunities and staking actions powered by Yield.xyz - name: Yield.xyz Borrow description: >- Supply collateral, borrow, repay and withdraw from lending markets (Aave V3, Morpho Blue, SparkLend, Lista) powered by Yield.xyz Borrow - name: Yield.xyz Perps description: >- Trade perpetual futures — open/close leveraged positions, manage stop-loss/take-profit, and fund/withdraw a trading account — powered by Yield.xyz Perps - name: Li.Fi description: Cross-chain swaps and bridging powered by Li.Fi - name: Blockaid description: Transaction and address security scanning powered by Blockaid - name: Hypernative description: >- Transaction, address, token, and NFT security scanning powered by Hypernative - name: Noah description: KYC onboarding, payins, and payouts powered by Noah - name: Meld description: Buy and sell crypto with fiat through aggregated providers powered by Meld - name: Due description: Payins, payouts, virtual accounts, and FX powered by Due - name: EIP-7702 description: EIP-7702 account type detection and authorization management - name: Deprecated description: >- Legacy endpoints scheduled for removal. Use the newer equivalents listed in each endpoint's description. paths: /clients/me/integrations/yield-xyz-perps/actions/{id}: get: tags: - Yield.xyz Perps summary: Get an action description: >- Get one action by id, with its unsigned transactions and current status. Poll this to track a multi-transaction action to `SUCCESS`. This is a proxy to the Yield.xyz Perps `GET /v1/actions/{id}` endpoint. Portal validates the upstream response against the schema documented here before returning it under `data`, and translates funding-chain `network` values to CAIP-2. If Yield.xyz changes the response shape, Portal returns a 500 with `id: INTEGRATION_RESPONSE_SCHEMA_DRIFT` instead of a partial response. Upstream reference: [Yield.xyz Perps API](https://docs.yield.xyz). operationId: getYieldXyzPerpsAction parameters: - name: id in: path required: true example: 550e8400-e29b-41d4-a716-446655440001 schema: type: string description: Action id. responses: '200': description: The action content: application/json: schema: $ref: '#/components/schemas/YieldXyzPerpsActionResponse' '400': description: >- Invalid request. Also returned when Yield.xyz Perps rejects the request or the configured API key; a vendor `details.code` is surfaced when present. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Yield.xyz Perps rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- Yield.xyz Perps returned a response that does not match the schema Portal expects (`id: INTEGRATION_RESPONSE_SCHEMA_DRIFT`). content: application/json: schema: $ref: '#/components/schemas/IntegrationSchemaDriftErrorResponse' '503': description: Yield.xyz Perps is unreachable or returned an upstream error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: YieldXyzPerpsActionResponse: type: object required: - data properties: data: $ref: '#/components/schemas/YieldXyzPerpsAction' ErrorResponse: type: object properties: error: type: string description: Error message describing what went wrong IntegrationSchemaDriftErrorResponse: type: object description: >- Returned (HTTP 500) when a third-party response no longer matches the schema Portal proxies for it. The `id` is stable: SDKs should key off it and fail gracefully. Portal is alerted automatically and fixes the mapping server-side. required: - error - id - details properties: error: type: string example: >- yield-xyz-borrow returned a response for GET /v1/positions that does not match the expected schema id: type: string enum: - INTEGRATION_RESPONSE_SCHEMA_DRIFT details: type: object required: - integration - endpoint - issues properties: integration: type: string example: yield-xyz-borrow endpoint: type: string description: The upstream vendor endpoint whose response drifted. example: GET /v1/positions issues: type: array items: type: object required: - path - message - code properties: path: type: string description: Dotted path of the offending field in the vendor response. example: supplyBalances.0.balanceUsd message: type: string example: Expected string, received number code: type: string example: invalid_type YieldXyzPerpsAction: type: object description: >- An action with its unsigned transactions and status. `signedMetadata` is opaque passthrough (returned untouched) for client-side verification. required: - id - providerId - action - status - summary - transactions - createdAt - completedAt properties: id: type: string example: 550e8400-e29b-41d4-a716-446655440001 providerId: type: string description: Venue slug (passed through unchanged). example: hyperliquid action: type: string description: >- Action type. Known values: `open`, `close`, `updateLeverage`, `stopLoss`, `takeProfit`, `cancelOrder`, `editOrder`, `fund`, `withdraw`, `approveAgent`, `approveBuilderFee`, `updateMargin`, `setTpAndSl`, `setUnifiedAccount`. Treat unknown values as opaque. example: open status: type: string description: >- Current action status. Known values: `CANCELED`, `CREATED`, `WAITING_FOR_NEXT`, `PROCESSING`, `FAILED`, `SUCCESS`, `STALE`. Treat unknown values as opaque. example: CREATED summary: nullable: true allOf: - $ref: '#/components/schemas/YieldXyzPerpsActionSummary' signedMetadata: description: Opaque action-level metadata, returned untouched. nullable: true oneOf: - type: string - type: object transactions: type: array description: Transactions for this action, in signing order. items: $ref: '#/components/schemas/YieldXyzPerpsTransaction' createdAt: type: string format: date-time example: '2026-08-26T10:30:00.000Z' completedAt: type: string format: date-time nullable: true example: '2026-08-26T10:30:05.000Z' YieldXyzPerpsActionSummary: type: object description: >- A human-readable summary of what an action will do. Only `type` is guaranteed. required: - type properties: type: type: string example: Open Position orderType: type: string description: 'Known values: `market`, `limit`.' example: market direction: type: string description: 'Known values: `long`, `short`.' example: long asset: type: string example: ETH price: type: number example: 3500 size: type: string example: '0.215' leverage: type: number example: 20 collateral: type: string example: '43.00' fee: type: string example: '0.0005' marginMode: type: string example: isolated estimatedLiquidationPrice: type: number example: 4200 additionalProperties: true YieldXyzPerpsTransaction: type: object description: >- An unsigned transaction to sign by its `signingFormat`. `signablePayload` and `rawPayload` are opaque passthrough (string or object, returned untouched) so the client can independently recompute the EIP-712 connection id; `chainId` is kept for that verification. required: - id - network - chainId - type - status - address - explorerUrls properties: id: type: string description: Transaction id (UUID). example: 550e8400-e29b-41d4-a716-446655440000 network: type: string description: >- Venue slug, or a CAIP-2 chain id for on-chain (funding/withdrawal) legs. example: hyperliquid chainId: type: string description: The EIP-712 domain chain id, kept exactly as the venue returns it. example: '1337' type: type: string description: >- Transaction type. Known values: `APPROVAL`, `OPEN_POSITION`, `CLOSE_POSITION`, `UPDATE_LEVERAGE`, `STOP_LOSS`, `TAKE_PROFIT`, `CANCEL_ORDER`, `EDIT_ORDER`, `FUND`, `WITHDRAW`, `APPROVE_BUILDER_FEE`, `ENABLE_DEX_ABSTRACTION`, `APPROVE_AGENT`, `UPDATE_MARGIN`, `SET_TP_AND_SL`, `SET_USER_ABSTRACTION`. Treat unknown values as opaque. example: OPEN_POSITION status: type: string description: >- Current transaction status. Known values: `CREATED`, `QUEUED`, `BROADCASTED`, `CONFIRMED`, `FAILED`, `NOT_FOUND`. Treat unknown values as opaque. example: CREATED address: type: string example: '0x1234567890abcdef1234567890abcdef12345678' args: description: Typed passthrough of the action arguments this transaction carries. allOf: - $ref: '#/components/schemas/YieldXyzPerpsArguments' signingFormat: type: string nullable: true description: >- Signing format required. Known values: `EVM_TRANSACTION`, `EIP712_TYPED_DATA`, `SOLANA_TRANSACTION`, `COSMOS_TRANSACTION`. Treat unknown values as opaque. example: EIP712_TYPED_DATA signablePayload: description: >- Opaque payload to sign, returned byte-for-byte. For `EVM_TRANSACTION` a JSON string of the unsigned transaction; for `EIP712_TYPED_DATA` the typed-data structure to hash and sign. oneOf: - type: string - type: object rawPayload: description: Opaque venue order the signature authorizes, returned byte-for-byte. nullable: true oneOf: - type: string - type: object explorerUrls: type: array items: type: string YieldXyzPerpsArguments: type: object description: >- Action arguments. Documented fields are typed; unknown keys pass through to the venue untouched (the venue's `argumentSchemas` from `GET /providers/{providerId}` is the source of truth for which `args` an action requires). `network` values here are venue slugs or CAIP-2 chains. additionalProperties: true properties: marketId: type: string description: Market id as returned by `GET /markets`. example: hyperliquid-eth-usdc side: type: string description: 'Position direction. Known values: `long`, `short`.' example: long amount: type: string description: >- Amount in human-readable units (e.g. collateral to fund or withdraw). example: '100' size: type: string description: Position size. example: '1000' leverage: type: number description: Leverage multiplier. example: 10 marginMode: type: string description: 'Known values: `isolated`, `cross`.' example: isolated limitPrice: type: number description: Limit price for a limit order. example: 3900 stopLossPrice: type: number description: Trigger price for a stop-loss. example: 3600 takeProfitPrice: type: number description: Trigger price for a take-profit. example: 4400 orderId: type: string description: A single order id (e.g. to cancel or edit). example: '12345' orderIds: type: array items: type: string description: Multiple order ids (e.g. to cancel several orders). assetIndex: type: number description: Venue-specific asset index. example: 1 fromToken: description: Funding source token and chain (for `fund`). allOf: - $ref: '#/components/schemas/YieldXyzPerpsTokenIdentifier' agentAddress: type: string description: Agent wallet address (for `approveAgent`). example: '0x1234567890abcdef1234567890abcdef12345678' agentName: type: string description: Human-readable agent name (for `approveAgent`). example: my-app validUntil: type: number description: Expiry (unix seconds) for a time-bounded approval. example: 1767225600 stopLossOrderId: type: string description: Existing stop-loss order id to update. example: '12346' takeProfitOrderId: type: string description: Existing take-profit order id to update. example: '12347' skipApproval: type: boolean description: Skip an approval step where the venue allows it. example: false fundingMethod: type: string description: 'How the venue routes a deposit. Known values: `bridge2`, `lifi`.' example: bridge2 enabled: type: boolean description: Toggle flag (e.g. for `setUnifiedAccount`). example: true YieldXyzPerpsTokenIdentifier: type: object description: >- A token reference. `network` is a venue slug or a CAIP-2 chain id; on requests a real funding chain must be CAIP-2 and is translated to the Yield.xyz network name. Unknown keys pass through. required: - network additionalProperties: true properties: network: type: string description: Venue slug or CAIP-2 chain id (e.g. `eip155:42161`). example: eip155:42161 address: type: string description: Token contract address on that network. example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' securitySchemes: bearerAuth: type: http scheme: bearer description: > Client API Key or Client Session Token (CST). Pass as a Bearer token in the Authorization header. ````