Positions

This is the simulated Earn API. Position creation and withdrawal change sandbox records; they do not sign a wallet transaction.

Authentication · Errors · Amounts and units

Open a position

POST /positions

Validates the wallet/asset/amount and routes to a vault. Settlement is synchronous: the position is active immediately.

Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| Idempotency-Key | header | string | No | Client-generated key. Retries with the same key replay the original response. |

Request body

Schema: CreatePositionRequest

Response · 201

Field	Type	Required	Description
object	string	Yes
data	Position	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.

List positions

GET /positions

Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| wallet | query | string | No | Filter by wallet address |

| status | query | "active", "closed" | No | Filter by status |

| limit | query | integer | No | Page size (1-500, default 100) |

| cursor | query | string | No | Opaque cursor returned as meta.next_cursor |

Response · 200

Field	Type	Required	Description
object	"list"	Yes
data	Position[]	Yes
meta	ListMeta	Yes

For failed requests, inspect error.code, error.message and the request ID. Error handling.

Get a position

GET /positions/{id}

Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| id | path | string | Yes | Position id |

Response · 200

Field	Type	Required	Description
object	string	Yes
data	Position	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.

Withdraw from a position

POST /positions/{id}/withdraw

Partial or full withdrawal. Partial withdrawals preserve accrued yield exactly (the remaining value keeps compounding).

Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| id | path | string | Yes | Position id |

Request body

Schema: WithdrawRequest

Response · 200

Field	Type	Required	Description
object	string	Yes
data	Position	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.

Position event timeline

GET /positions/{id}/history

Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| id | path | string | Yes | Position id |

| limit | query | integer | No | Page size (1-500, default 100) |

| cursor | query | string | No | Opaque cursor returned as meta.next_cursor |

Response · 200

Field	Type	Required	Description
object	"list"	Yes
data	PositionEvent[]	Yes
meta	ListMeta	Yes

For failed requests, inspect error.code, error.message and the request ID. Error handling.