Skip to main content
POST
/
api
/
v1
/
signals
创建信号
curl --request POST \
  --url https://api.dev.akria.net/api/v1/signals \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-02T10:00:00Z",
  "priority": "high",
  "title": "AI 板块出现集中放量",
  "summary": "多个AI相关代币在5分钟内成交量激增，同时Twitter上相关话题提及量增长230%",
  "evidence": {
    "market": {
      "symbols": [
        "AI1",
        "AI2",
        "AI3"
      ],
      "volume_increase": "320%",
      "price_change_range": "5-12%"
    },
    "twitter": {
      "topic": "AI Meme",
      "tweet_growth": 500,
      "key_accounts": [
        "@influencer1",
        "@influencer2"
      ]
    }
  },
  "expire_at": "2026-02-02T11:00:00Z"
}
'
{
  "id": 1,
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-02T10:00:00Z",
  "priority": "high",
  "title": "AI 板块出现集中放量",
  "summary": "多个AI相关代币在5分钟内成交量激增",
  "evidence": {
    "market": {
      "symbols": ["AI1", "AI2", "AI3"],
      "volume_increase": "320%"
    },
    "twitter": {
      "topic": "AI Meme",
      "tweet_growth": 500
    }
  },
  "expire_at": "2026-02-02T11:00:00Z",
  "status": "dispatching",
  "received_at": "2026-02-02T10:00:05.123456Z",
  "created_at": "2026-02-02T10:00:05.123456Z",
  "updated_at": "2026-02-02T10:00:05.123456Z"
}
接收来自分析层的已审计信号，验证并创建 outbox 记录。

​
核心特性

字段验证

验证所有必填字段，确保数据完整性

过期检查

expire_at 必须未来时间，拒绝已过期信号

幂等性保证

signal_id UNIQUE，重复提交返回已有记录

自动生成 Outbox

为每个信号生成 2 条 outbox（ghost + rocketchat）

​
认证

所有 API 端点（除健康检查外）都需要在请求头中包含 API Key。
X-API-Key: your-api-key-here
联系管理员获取你所在组的 API Key。每个组有独立的 API Key，便于管理和追踪。

​
请求参数

​
Headers

参数类型必填说明
X-API-Keystring✅API 认证密钥
Content-Typestring✅application/json

​
Body 参数

字段类型必填说明示例
signal_idUUID✅信号唯一标识（用于幂等性）550e8400-e29b-41d4-a716-446655440000
timestampdatetime✅信号发生时间（ISO 8601，UTC）2026-02-02T10:00:00Z
prioritystring✅优先级：high / medium / lowhigh
titlestring✅信号标题（最大 100 字符）AI 板块出现集中放量
summarystring✅信号摘要多个AI相关代币在5分钟内成交量激增
evidenceobject✅证据数据（JSON 对象）{"market": {...}, "twitter": {...}}
expire_atdatetime✅过期时间（ISO 8601，UTC，必须未来时间）2026-02-02T11:00:00Z

​
响应

​
成功响应（201 Created）

信号已创建，并生成了 outbox 记录。 
{
  "id": 1,
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-02T10:00:00Z",
  "priority": "high",
  "title": "AI 板块出现集中放量",
  "summary": "多个AI相关代币在5分钟内成交量激增",
  "evidence": {
    "market": {
      "symbols": ["AI1", "AI2", "AI3"],
      "volume_increase": "320%"
    },
    "twitter": {
      "topic": "AI Meme",
      "tweet_growth": 500
    }
  },
  "expire_at": "2026-02-02T11:00:00Z",
  "status": "dispatching",
  "received_at": "2026-02-02T10:00:05.123456Z",
  "created_at": "2026-02-02T10:00:05.123456Z",
  "updated_at": "2026-02-02T10:00:05.123456Z"
}
状态说明：dispatching 表示已创建 outbox，正在分发中。

​
幂等性响应（200 OK）

使用相同的 signal_id 再次提交，返回已有记录。 
{
  "id": 1,
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-02T10:00:00Z",
  "priority": "high",
  "title": "AI 板块出现集中放量",
  "summary": "多个AI相关代币在5分钟内成交量激增",
  "evidence": {...},
  "expire_at": "2026-02-02T11:00:00Z",
  "status": "dispatching",
  "received_at": "2026-02-02T10:00:05.123456Z",
  "created_at": "2026-02-02T10:00:05.123456Z",
  "updated_at": "2026-02-02T10:00:05.123456Z"
}

​
错误响应

{
  "detail": "expire_at must be in the future"
}
常见错误：
  • expire_at must be in the future: 过期时间已过
  • Signal has already expired: 信号已过期
  • Field required: 缺少必填字段
  • priority must be one of: high, medium, low: 优先级无效
  • Database integrity error: ...: 数据库约束错误（如重复的 signal_id）
{
  "detail": "Internal server error"
}
说明：
  • 生产环境：返回通用错误信息 "Internal server error"
  • 开发环境（DEBUG 模式）：返回详细错误信息，格式为 "{ErrorType}: {error_message}"
生产环境不会返回详细的错误堆栈，这是出于安全考虑。如需调试，请查看服务器日志。
{
  "detail": "Invalid API Key"
}
如果 API Key 错误或缺失，会返回 401 Unauthorized。请检查请求头中的 X-API-Key 是否正确。

​
使用示例

curl -X POST https://api.dev.akria.net/api/v1/signals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "signal_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-02T10:00:00Z",
    "priority": "high",
    "title": "AI 板块出现集中放量",
    "summary": "多个AI相关代币在5分钟内成交量激增，同时Twitter上相关话题提及量增长230%",
    "evidence": {
      "market": {
        "symbols": ["AI1", "AI2", "AI3"],
        "volume_increase": "320%",
        "price_change_range": "5-12%"
      },
      "twitter": {
        "topic": "AI Meme",
        "tweet_growth": 500,
        "key_accounts": ["@influencer1", "@influencer2"]
      }
    },
    "expire_at": "2026-02-02T11:00:00Z"
  }'

​
注意事项

signal_id 必须唯一

使用 UUID v4 生成，确保全局唯一性

expire_at 必须未来时间

建议至少 1 小时后，避免立即过期

幂等性保证

相同 signal_id 不会重复创建 outbox

时区要求

所有时间字段使用 UTC（ISO 8601 格式，带 Z）

​
相关文档

团队使用手册

手把手教程，适合团队使用

拉取 Outbox

下游服务拉取待投递内容

ACK 确认

下游服务投递完成后发送 ACK 确认

Authorizations

​
X-API-Key
string
header
required

API 认证密钥

Body

application/json
​
signal_id
string<uuid>
required

信号唯一标识（用于幂等性）

​
timestamp
string<date-time>
required

信号发生时间（ISO 8601，UTC）

​
priority
enum<string>
required

优先级

Available options:
high,
medium,
low
​
title
string
required

信号标题

Maximum string length: 100
​
summary
string
required

信号摘要

​
evidence
object
required

证据数据（JSON 对象）

​
expire_at
string<date-time>
required

过期时间（ISO 8601，UTC，必须未来时间）

Response

幂等性响应：信号已存在

​
id
integer

信号 ID

​
signal_id
string<uuid>

信号唯一标识

​
timestamp
string<date-time>

信号发生时间

​
priority
enum<string>

优先级

Available options:
high,
medium,
low
​
title
string

信号标题

​
summary
string

信号摘要

​
evidence
object

证据数据

​
expire_at
string<date-time>

过期时间

​
status
enum<string>

信号状态

Available options:
accepted,
dispatching,
sent,
partial_sent,
failed,
archived
​
received_at
string<date-time>

接收时间

​
created_at
string<date-time>

创建时间

​
updated_at
string<date-time>

更新时间