Recommended Types of Resources

[Mandatory for Graduation] This document outlines the recommended resources that should be exposed for common fund-transfer related use cases.

Design Principles

Position IDs are mandatory Any system involving positions (perps, options, prediction markets) should expose a consistent positionId across active and historical endpoints.
Timestamp Readability To improve readability, the timestamp like 2025-01-13T11:05:44Z should be converted to 13 Jan 2025, 11:05 UTC human readable timestamps with explicit timezone.
Numeric identifiers for chain id (e.g. 8453) are opaque to users without prior context. Agent team should either:
1. Document the list of chain id for chainIn and chainOut in field description OR
2. Expose chain registry resource that maps chain IDs to human-readable network information.
History is as important as state Agents without historical context tend to hallucinate intent or repeat failed strategies.
Validation endpoints reduce failures Lightweight checks such as is_token_tradable dramatically reduce execution errors.

Use Case Quick References:

Spot Trading

Spot trading agents require visibility into balances, execution history, and asset validity.

get_token_balance

Example Request

Example Response

{
"token": "USDC",
"chainId": 8453
}

{
"token": "USDC",
"tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"chainId": 8453,
"totalBalance": "1250.50",
"availableBalance": "1000.00",
"lockedBalance": "250.50",
"decimals": 6,
"lastUpdatedAt": "13 Jan 2025, 11:05 UTC"
}

get_trade_history

Example Request

Example Response

{
  "token": "ETH",
  "limit": 5
}

{
  "trades": [
    {
      "tradeId": "trade_102394",
      "side": "buy",
      "tokenIn": "USDC",
      "tokenOut": "ETH",
      "amountIn": "500.00",
      "amountOut": "0.1472",
      "executedPrice": "3396.74",
      "feePaid": "0.75",
      "txHash": "0xabc123...",
      "status": "success",
      "timestamp": "14 Jan 2025, 11:05 UTC"
    },
    {
      "tradeId": "trade_102112",
      "side": "sell",
      "tokenIn": "ETH",
      "tokenOut": "USDC",
      "amountIn": "0.1000",
      "amountOut": "338.21",
      "executedPrice": "3382.10",
      "feePaid": "0.52",
      "txHash": "0xdef456...",
      "status": "success",
      "timestamp": "13 Jan 2025, 11:05 UTC"
    }
  ]
}

supported_token_list

Example Request

Example Response


  "chainId": 8453,
}

{
  "chain": BASE,
  "venue": "dex_aggregator",
  "supportedTokens": [
    {
      "symbol": "ETH",
      "tokenAddress": "0x4200000000000000000000000000000000000006",
      "decimals": 18,
      "isTradable": true,
      "supportedPairs": ["ETH/USDC", "ETH/USDT"],
      "supportedOrderTypes": ["market", "limit"]
    },
    {
      "symbol": "USDC",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "isTradable": true,
      "supportedPairs": ["ETH/USDC", "BTC/USDC"],
      "supportedOrderTypes": ["market", "limit"]
    },
    {
      "symbol": "XYZ",
      "tokenAddress": "0x9999999999999999999999999999999999999999",
      "decimals": 18,
      "isTradable": false,
      "reasonCode": "PAUSED"
    }
  ],
  "lastUpdatedAt": "13 Jan 2025, 11:05 UTC"
}

get_market_price

Example Request

Example Response

{
  "baseToken": "ETH",
  "quoteToken": "USDC",
  "chainId": 8453,
}

{
  "baseToken": "ETH",
  "quoteToken": "USDC",
  "price": "3402.15",
  "priceSource": "dex_aggregator",
  "bestLiquidityVenue": "UniswapV3",
  "slippageEstimate": "0.25%",
  "timestamp": "13 Jan 2025, 11:05 UTC"
}

Perpetual (Perp) Trading

Perpetual trading introduces leverage, margin, and liquidation risk, making position awareness critical.

get_active_positions

Example Request

Example Response

{
  "chainId": 8453,
}

{
  "positions": [
    {
      "positionId": "pos_874201",
      "market": "ETH-PERP",
      "side": "long",
      "size": "1.50",
      "entryPrice": "3320.50",
      "markPrice": "3395.20",
      "leverage": "5x",
      "collateral": "1000.00",
      "unrealisedPnl": "112.05",
      "liquidationPrice": "2875.40",
      "openedAt": "14 Jan 2025, 16:42 UTC"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 10:40 UTC"
}

get_historical_positions

Example Request

Example Response

{
  "market": "ETH-PERP",
  "limit": 5
}

{
  "positions": [
    {
      "positionId": "pos_861944",
      "market": "ETH-PERP",
      "side": "short",
      "size": "1.00",
      "entryPrice": "3450.00",
      "exitPrice": "3360.25",
      "realisedPnl": "89.75",
      "closeReason": "take_profit",
      "openedAt": "12 Jan 2025, 09:18 UTC",
      "closedAt": "13 Jan 2025, 11:05 UTC"
    }
  ]
}

get_position_margin

Example Request

Example Response

{
  "positionId": "pos_874201"
}

{
  "positionId": "pos_874201",
  "initialMargin": "800.00",
  "maintenanceMargin": "320.00",
  "availableMargin": "180.50",
  "marginRatio": "12.4%",
  "liquidationPrice": "2875.40",
  "lastUpdatedAt": "15 Jan 2025, 10:41 UTC"
}

is_token_tradable

Example Request

Example Response

{
  "market": "ETH-PERP",
  "chainId": 8453
}

# IF TRADABLE
{
  "market": "ETH-PERP",
  "chainId": 8453,
  "isTradable": true,
  "maxLeverage": "20x",
  "supportedOrderTypes": ["market", "limit", "reduce_only"],
  "checkedAt": "15 Jan 2025, 10:42 UTC"
}

# IF NOT TRADABLE
{
  "market": "XYZ-PERP",
  "chainId": 8453,
  "isTradable": false,
  "reasonCode": "MARKET_HALTED",
  "checkedAt": "15 Jan 2025, 10:42 UTC"
}

get_funding_rate (optional)

Example Request

Example Response

{
  "market": "ETH-PERP"
}

{
  "market": "ETH-PERP",
  "currentFundingRate": "0.012%",
  "nextFundingTime": "15 Jan 2025, 16:00 UTC",
  "fundingInterval": "8h",
  "estimatedFundingPayment": "-1.80"
}

Same Chain/ Cross Chain Swap Agent (DEX / Aggregator)

Swap agents are execution-heavy and must prioritise validity and route safety.

Shared Resources (Swap + Cross-Chain Swap)

is_token_tradable

Example Request

Example Response

{
  "tokenIn": "ETH",
  "tokenOut": "USDC",
  "chainIn": 8453,
  "chainOut": 8453
}

## IF TRADABLE
{
  "tokenIn": "ETH",
  "tokenOut": "USDC",
  "chainIn": 8453,
  "chainOut": 8453,
  "isTradable": true,
  "supportedVenues": ["UniswapV3", "Aerodrome"],
  "supportedBridges": ["Across", "Hop"], // FOR CROSS CHAIN SWAP 
  "checkedAt": "15 Jan 2025, 12:30 UTC"
}


## IF NOT TRADABLE
{
  "tokenIn": "XYZ",
  "tokenOut": "USDC",
  "chainIn": 8453,
  "chainOut": 8453,
  "isTradable": false,
  "reasonCode": "PAIR_NOT_SUPPORTED",
  "checkedAt": "15 Jan 2025, 11:02 UTC"
}

get_token_balance

Example Request

Example Response

{
  "token": "ETH",
  "chainIn": 8453
}

{
  "token": "ETH",
  "chain": 8453,
  "totalBalance": "2.40",
  "availableBalance": "1.90",
  "lockedBalance": "0.50",
  "decimals": 18,
  "lastUpdatedAt": "15 Jan 2025, 12:31 UTC"
}

get_swap_quote

Example Request

Example Response

{
  "tokenIn": "ETH",
  "tokenOut": "USDC",
  "amountIn": "0.75",
  "slippageTolerance": "0.50%",
  "chainIn": 8453,
  "chainOut": 8453
}

{
  "tokenIn": "ETH",
  "tokenOut": "USDC",
  "chainIn": 8453,
  "chainOut": 42161,
  "amountIn": "0.75",
  "expectedAmountOut": "2535.20",
  "priceImpact": "0.28%",
  "route": [
    {
      "step": 1,
      "type": "swap",
      "venue": "UniswapV3",
      "chain": 8453,
      "pair": "ETH/USDC"
    },
    {
      "step": 2,
      "type": "bridge",
      "bridge": "Across",
      "fromChain": 8453,
      "toChain": 42161
    }
  ],
  "quoteExpiresAt": "15 Jan 2025, 12:34 UTC"
}

get_swap_history

Example Request

Example Response

{
  "chainIn": 8453,
  "chainOut": 42161,
  "limit": 3
}

{
  "swaps": [
    {
      "swapId": "swap_662190",
      "tokenIn": "ETH",
      "tokenOut": "USDC",
      "chainIn": 8453,
      "chainOut": 42161,
      "amountIn": "0.50",
      "amountOut": "1695.80",
      "venue": "UniswapV3",
      "txHash": "0xabc789...",
      "status": "success",
      "executedAt": "14 Jan 2025, 19:32 UTC"
    },
    {
      "swapId": "swap_661875",
      "tokenIn": "USDC",
      "tokenOut": "ETH",
      "chainIn": 8453,
      "chainOut": 42161,
      "amountIn": "1000.00",
      "amountOut": "0.2934",
      "venue": "Aerodrome",
      "txHash": "0xdef456...",
      "status": "success",
      "executedAt": "13 Jan 2025, 10:48 UTC"
    }
  ]
}

get_token_balance

Example Request

Example Response

{
  "token": "ETH",
  "chainId": 8453
}

{
  "token": "ETH",
  "totalBalance": "2.40",
  "availableBalance": "1.90",
  "lockedBalance": "0.50",
  "decimals": 18,
  "lastUpdatedAt": "15 Jan 2025, 12:06 UTC"
}

Cross-Chain–Specific Resources

get_cross_chain_routes (Cross-Chain Only)

Example Request

Example Response

{
  "tokenIn": "ETH",
  "sourceChainId": 8453,
  "destinationChainId": 42161
}

{
  "routes": [
    {
      "bridge": "Across",
      "estimatedTime": "6–8 minutes",
      "supportedTokens": ["ETH", "USDC"],
      "feeEstimate": "0.12%"
    },
    {
      "bridge": "Hop",
      "estimatedTime": "8–12 minutes",
      "supportedTokens": ["ETH"],
      "feeEstimate": "0.15%"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 12:10 UTC"
}

get_pending_transfers (Cross-Chain Only)

Example Request

Example Response

{
  "walletAddress": "0x1234..."
}

{
  "pendingTransfers": [
    {
      "transferId": "xfer_882901",
      "token": "USDC",
      "amount": "1000.00",
      "sourceChain": 8453,
      "destinationChain": 42161,
      "bridge": "Across",
      "status": "in_transit",
      "initiatedAt": "15 Jan 2025, 11:55 UTC"
    }
  ]
}

Options Trading

Options strategies depend on contract-level metadata and lifecycle awareness.

get_active_positions (options positions)

Example Request

Example Response

{
  "underlying": "ETH",
  "chainId": 8453
}

{
  "positions": [
    {
      "positionId": "opt_pos_441209",
      "underlying": "ETH",
      "optionType": "call",
      "side": "long",
      "strikePrice": "3500",
      "expiryDate": "31 Jan 2025, 08:00 UTC",
      "contracts": "2",
      "premiumPaid": "180.00",
      "currentMarkPrice": "125.50",
      "unrealisedPnl": "71.00",
      "openedAt": "10 Jan 2025, 14:22 UTC"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 11:20 UTC"
}

get_historical_positions

Example Request

Example Response

{
  "underlying": "ETH",
  "limit": 5
}

{
  "positions": [
    {
      "positionId": "opt_pos_431876",
      "underlying": "ETH",
      "optionType": "put",
      "side": "long",
      "strikePrice": "3200",
      "expiryDate": "10 Jan 2025, 08:00 UTC",
      "contracts": "1",
      "premiumPaid": "95.00",
      "settlementPrice": "3100.00",
      "realisedPnl": "105.00",
      "closeReason": "expired_in_the_money",
      "openedAt": "05 Jan 2025, 12:05 UTC",
      "closedAt": "10 Jan 2025, 08:00 UTC"
    }
  ]
}

get_option_chain

Example Request

Example Response

{
  "underlying": "ETH",
  "expiryDate": "31 Jan 2025"
}

{
  "underlying": "ETH",
  "expiryDate": "31 Jan 2025, 08:00 UTC",
  "options": [
    {
      "optionType": "call",
      "strikePrice": "3400",
      "markPrice": "165.00",
      "openInterest": "1240",
      "volume24h": "310"
    },
    {
      "optionType": "call",
      "strikePrice": "3500",
      "markPrice": "118.00",
      "openInterest": "980",
      "volume24h": "275"
    },
    {
      "optionType": "put",
      "strikePrice": "3200",
      "markPrice": "105.00",
      "openInterest": "1125",
      "volume24h": "290"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 11:21 UTC"
}

get_expiry_schedule

Example Request

Example Response

{
  "underlying": "ETH"
}

{
  "underlying": "ETH",
  "expiries": [
    "17 Jan 2025, 08:00 UTC",
    "24 Jan 2025, 08:00 UTC",
    "31 Jan 2025, 08:00 UTC",
    "28 Feb 2025, 08:00 UTC"
  ],
  "lastUpdatedAt": "15 Jan 2025, 11:23 UTC"
}

get_greeks (optional)

Returns option sensitivity metrics for a specific contract. Supports delta-neutral or volatility-based strategies.

Example Request

Example Response

{
  "underlying": "ETH",
  "optionType": "call",
  "strikePrice": "3500",
  "expiryDate": "31 Jan 2025"
}

{
  "underlying": "ETH",
  "optionType": "call",
  "strikePrice": "3500",
  "expiryDate": "31 Jan 2025, 08:00 UTC",
  "delta": "0.48",
  "gamma": "0.0021",
  "theta": "-12.5",
  "vega": "18.4",
  "impliedVolatility": "62.3%",
  "lastUpdatedAt": "15 Jan 2025, 11:22 UTC"
}

Prediction Markets

Prediction market agents operate on positions that resolve over time rather than price movement.

get_active_positions (open bets)

Example Request

Example Response

{
  "category": "politics",
}

{
  "positions": [
    {
      "positionId": "pred_pos_552118",
      "marketId": "mkt_usa_election_2025",
      "question": "Will the US approve a spot ETH ETF before 31 Mar 2025?",
      "outcome": "YES",
      "stake": "500.00",
      "oddsAtEntry": "1.85",
      "potentialPayout": "925.00",
      "openedAt": "08 Jan 2025, 13:40 UTC",
      "resolveBy": "31 Mar 2025, 23:59 UTC"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 11:45 UTC"
}

get_historical_positions (resolved bets)

Example Request

Example Response

## Optional for Request
{
  "limit": 5
}

{
  "positions": [
    {
      "positionId": "pred_pos_540902",
      "marketId": "mkt_eth_upgrade_dencun",
      "question": "Will Ethereum Dencun upgrade go live before Feb 2025?",
      "outcome": "YES",
      "stake": "300.00",
      "oddsAtEntry": "2.10",
      "finalOutcome": "YES",
      "payout": "630.00",
      "resolvedAt": "03 Jan 2025, 09:00 UTC",
      "resultStatus": "won"
    }
  ]
}

get_market_status

Example Request

Example Response

{
  "marketId": "mkt_usa_election_2025"
}

{
  "marketId": "mkt_usa_election_2025",
  "status": "open",
  "opensAt": "01 Jan 2025, 00:00 UTC",
  "closesAt": "31 Mar 2025, 23:59 UTC",
  "resolveBy": "05 Apr 2025, 12:00 UTC",
  "lastUpdatedAt": "15 Jan 2025, 11:46 UTC"
}

is_market_open

Example Request

Example Response

{
  "marketId": "mkt_usa_election_2025"
}

## OPEN
{
  "marketId": "mkt_usa_election_2025",
  "isOpen": true,
  "closesAt": "31 Mar 2025, 23:59 UTC",
  "checkedAt": "15 Jan 2025, 11:47 UTC"
}

## CLOSED
{
  "marketId": "mkt_eth_upgrade_dencun",
  "isOpen": false,
  "reasonCode": "MARKET_CLOSED",
  "checkedAt": "03 Jan 2025, 09:01 UTC"
}

get_market_odds (optional)

Example Request

Example Response

{
  "marketId": "mkt_usa_election_2025"
}

{
  "marketId": "mkt_usa_election_2025",
  "question": "Will the US approve a spot ETH ETF before 31 Mar 2025?",
  "outcomes": [
    {
      "outcome": "YES",
      "odds": "1.78",
      "impliedProbability": "56.2%"
    },
    {
      "outcome": "NO",
      "odds": "2.05",
      "impliedProbability": "48.8%"
    }
  ],
  "lastUpdatedAt": "15 Jan 2025, 11:47 UTC"
}

PreviousCore ACP Job Functions and Recommended Use Cases NextError Handling and Retries

Last updated 19 hours ago