Financial Data

Twelve data

Learn how to use Twelve data with Composio

Overview

SLUG: TWELVE_DATA

Description

Twelve Data provides a comprehensive financial data API offering real-time and historical market data for stocks, forex, cryptocurrencies, ETFs, and indices.

Authentication Details

generic_api_key
stringRequired

Connecting to Twelve data

Create an auth config

Use the dashboard to create an auth config for the Twelve data toolkit. This allows you to connect multiple Twelve data accounts to Composio for agents to use.

1

Select App

Navigate to [Twelve data](https://platform.composio.dev?next_page=/marketplace/Twelve data).

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Twelve data Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4twelve_data_auth_config_id = "ac_YOUR_TWELVE_DATA_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10    # Replace this with a method to retrieve an API key from the user.
11    # Or supply your own.
12    user_api_key = input("[!] Enter API key")
13
14    connection_request = composio.connected_accounts.initiate(
15        user_id=user_id,
16        auth_config_id=auth_config_id,
17        config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18    )
19
20    # API Key authentication is immediate - no redirect needed
21    print(f"Successfully connected Twelve data for user {user_id}")
22    print(f"Connection status: {connection_request.status}")
23    
24    return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, twelve_data_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the [Twelve data toolkit’s playground](https://app.composio.dev/app/Twelve data)

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["TWELVE_DATA"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: List Commodities

Description

Tool to retrieve a list of supported commodities. use when you need all available commodities after obtaining a valid api key.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Cryptocurrencies

Description

Tool to list all supported cryptocurrencies. use when you need the complete set of crypto symbols. use after obtaining a valid api key.

Action Parameters

apikey
stringRequired
outputsize
integer
symbol
string

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: Currency Conversion

Description

Tool to convert an amount from one currency to another. use after confirming currency codes to retrieve real-time conversion.

Action Parameters

amount
numberRequired
from_currency
stringRequired
to_currency
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Dividends

Description

Tool to retrieve dividend payout history for a specified symbol. use when you need historical dividends over multiple years.

Action Parameters

country
string
delimiter
stringDefaults to ,
end_date
string
exchange
string
format
stringDefaults to JSON
outputsize
integerDefaults to 30
start_date
string
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Earnings

Description

Tool to retrieve earnings data including eps estimates and actuals. use when you need detailed earnings history for a selected stock symbol.

Action Parameters

format
string
source
string
symbol
stringRequired
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: EPS Revisions

Description

Tool to provide analysts’ revisions of a company’s future eps over the last week and month. use after confirming the stock symbol.

Action Parameters

dp
integer
exchange
string
format
stringDefaults to json
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: EPS Trend

Description

Tool to retrieve historical eps trends for a specified company. use after selecting a stock symbol to view estimated vs actual eps and surprise indicators. returns a breakdown of eps actuals, estimates, differences, and surprise percentages.

Action Parameters

format
stringDefaults to JSON
interval
stringDefaults to 1day
outputsize
integerDefaults to 30
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: ETFS Directory

Description

Tool to fetch a daily updated list of exchange-traded funds sorted by total assets. use when you need a directory of etfs by exchange or country.

Action Parameters

country
string
exchange
string
format
stringDefaults to JSON

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: ETFS Family

Description

Tool to fetch a comprehensive list of etfs by family. use when you need to list etfs managed by a specific investment company.

Action Parameters

family
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get ETF Types

Description

Tool to retrieve etf categories by market, including types like 'equity precious metals'. use after confirming api key is set; no parameters are needed.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List supported exchanges

Description

Tool to retrieve a list of supported exchanges. use when you need all available stock and forex exchanges.

Action Parameters

country
string
format
stringDefaults to json

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List supported forex pairs

Description

Tool to retrieve a list of all supported forex currency pairs. use when exploring available forex pairs before making other forex data requests.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List market indices

Description

Tool to retrieve a list of market indices. use when you need to fetch available indices filtered by country.

Action Parameters

country
string
format
stringDefaults to json

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Mutual Funds Family

Description

Tool to list all available mutual fund families. use when you need a comprehensive list of mutual fund families managed by investment companies after obtaining a valid api key.

Action Parameters

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: Mutual Funds List

Description

Tool to retrieve a daily updated list of mutual funds sorted by total assets. use when you need to enumerate available mutual funds for analysis.

Action Parameters

country
string
exchange
string
format
stringDefaults to json
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Options Chain

Description

Tool to retrieve the options chain for a given symbol and optional expiration date. use when you need detailed option contract data and greeks. omitting date returns all expirations.

Action Parameters

date
string
includeGreeks
boolean
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Options Expiration

Description

Tool to retrieve available option expiration dates. use when exploring available expiration dates for a given options symbol.

Action Parameters

exchange
string
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Quote

Description

Tool to retrieve the latest market data for a specified symbol. use when you need a quick real-time quote after selecting a symbol.

Action Parameters

format
string
source
string
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Stocks

Description

Tool to retrieve a list of stocks. use when you need to fetch securities with optional filtering by exchange, country, type, or symbol.

Action Parameters

country
string
exchange
string
format
stringDefaults to json
symbol
string
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Technical Indicators

Description

Tool to fetch time-series data for a specific technical indicator. use when you have a symbol, interval, and indicator name.

Action Parameters

indicator
stringRequired
indicator_params
object
interval
stringRequired
outputsize
integer
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Time Series

Description

Tool to retrieve historical and real-time time series data for a specified symbol. use when you need to fetch price data over a time range after selecting a symbol.

Action Parameters

end_date
string
format
stringDefaults to JSON
interval
stringRequired
outputsize
integerDefaults to 30
start_date
string
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired