API

Mimic API provides a secure and modular interface to automate tasks, and coordinate relayer-based executions across blockchains.

1. Authentication

1.1. Nonce

Request a new nonce for a wallet address. Used to initialize the signature-based login flow.

POST /users/nonce

Request

{
  "address": "address"
}

Response

{
  "address": "address",
  "nonce": "hash"
}

1.2. Authenticate

Authenticate a user by signing the nonce with their wallet.

POST /users/authenticate

Request

{
  "address": "address",
  "signature": "signature"
}

Response

{
  "address": "address",
  "token": "string"
}

---

2. Users

2.1. Api key

Fetch a user API key.

GET /users/api-key

Requires authentication with x-auth-token.

Response

{
  "address": "address",
  "apiKey": "string"
}

2.2. Tokens

Fetch a list of the user’s non-zero balances and allowances granted to settlers.

GET /users/tokens

Requires authentication with x-auth-token.

Response

[
  {
    "chainId": "number",
    "address": "address",
    "symbol": "string",
    "decimals": "number",
    "balance": "number",
    "allowance": "number"
  }
]

2.3. Balances

Manage protocol balances.

2.3.1. Create/update balance entry

POST /balances

Request

{
  "address": "address",
  "amount": "number",
  "description": "string"
}

Response

{
  "address": "address",
  "amount": "number",
  "description": "string",
  "createdAt": "ISO date",
  "expiresAt": "optional ISO date"
}

2.3.2. All balances

Query balances with optional filters.

GET /balances

Query Parameters

• address: Ethereum address (optional)

• offset: number (default: 0)

• limit: number (default: 20)

• sort: string (asc | desc, default: desc)

Response

[
  {
    "address": "address",
    "amount": "number",
    "description": "string",
    "createdAt": "ISO date",
    "expiresAt": "optional ISO date"
  }
]

2.3.3. Balance total

Get the current total balance for an address.

GET /balances/:address/total

Response

{
  "address": "address",
  "balance": "number"
}

---

3. Tasks

3.1. Create task

Upload a task manifest and files. Returns a CID pointing to the task.

POST /tasks

Requires authentication with x-api-key and file upload (multipart/form-data).

Response

{
  "CID": "CID",
  "name": "string",
  "version": "string",
  "description": "string",
  "creator": "address",
  "createdAt": "ISO date"
}

3.2. All tasks

Query tasks with optional filters.

GET /tasks

Query Parameters

• cids: string[]

• creator: Ethereum address

• offset: number (default: 0)

• limit: number (default: 20)

Response

[
  {
    "CID": "CID",
    "name": "string",
    "version": "string",
    "description": "string",
    "creator": "address",
    "createdAt": "ISO date"
  }
]

3.3. Find task

Retrieve a task by its CID.

GET /tasks/:cid

Response

{
  "CID": "CID",
  "name": "string",
  "version": "string",
  "description": "string",
  "creator": "address",
  "createdAt": "ISO date"
}

3.4. Task manifest

Retrieve the task manifest from IPFS.

GET /tasks/:cid/manifest

Headers:

• Cache-Control: public, max-age=3600

• ETag: <cid>

• Content-Type: application/json

3.5. Task WASM binary

Retrieve the task WASM binary from IPFS.

GET /tasks/:cid/wasm

Returns a binary payload with appropriate content headers.

---

4. Configs

4.1. Create config

Create a new task configuration. Includes signature verification.

POST /configs

The types fields must be in the order they appear below. The Input elements must match the task manifest inputs, in the same order.

Request

{
  "description": "string",
  "typedData": {
    "types": {
      "Input": [{ "name": "string", "type": "string" }],
      "Trigger": [{ "name": "string", "type": "string" }],
      "Config": [{ "name": "string", "type": "string" }]
    },
    "values": {
      "taskCid": "CID",
      "version": "string (semver)",
      "input": {},
      "trigger": {}
    }
  },
  "sig": "signature"
}

Response

{
  "sig": "signature",
  "taskCid": "CID",
  "signer": "address",
  "version": "string",
  "active": true,
  "description": "string",
  "input": {},
  "trigger": {},
  "executionFeeLimit": "number",
  "minValidations": "number",
  "types": { "Input": [], "Trigger": [], "Config": []},
  "createdAt": "ISO date"
}

4.2. All configs

Fetch a list of task configurations with optional filters.

GET /configs

Query Parameters

• sigs: string[]

• taskCid: string (CID)

• signer: Ethereum address

• active: boolean

• createdAfter: timestamp

• createdBefore: timestamp

• offset: number (default: 0)

• limit: number (default: 20)

Response

[
  {
    "sig": "signature",
    "taskCid": "CID",
    "signer": "address",
    "version": "string",
    "active": "boolean",
    "description": "string",
    "input": {},
    "trigger": {},
    "executionFeeLimit": "number",
    "minValidations": "number",
    "types": { "Input": [], "Trigger": [], "Config": []},
    "createdAt": "ISO date"
  }
]

4.3. Find config

Fetch a specific task configuration by signature.

GET /configs/:sig

Response

{
  "sig": "signature",
  "taskCid": "CID",
  "signer": "address",
  "version": "string",
  "active": "boolean",
  "description": "string",
  "input": {},
  "trigger": {},
  "executionFeeLimit": "number",
  "minValidations": "number",
  "types": { "Input": [], "Trigger": [], "Config": []},
  "createdAt": "ISO date"
}

---

4.4. Deactivate config

Deactivates a specific task configuration by signature. Includes signature verification.

POST /configs/:sig/deactivate

This change cannot be reverted.

Request

{
  "deactivateSig": "signature"
}

Response

{
  "sig": "signature",
  "taskCid": "CID",
  "signer": "address",
  "active": false,
  "description": "string",
  "input": {},
  "trigger": {},
  "executionFeeLimit": "number",
  "minValidations": "number",
  "types": { "Input": [], "Trigger": [], "Config": []},
  "createdAt": "ISO date"
}

---

5. Executions

5.1. Create execution

Creates a new relayer task execution.

POST /executions

Request

{
  "configSig": "signature",
  "triggerType": "string",
  "triggerData": {},
  "timestamp": "ISO date",
  "inputs": [
    {
      "signature": "signature",
      "query": {},
      "result": {}
    }
  ],
  "outputs": [
    {
      "op": 0,
      "user": "address",
      "settler": "address",
      "nonce": "hex",
      "deadline": "ISO date",
      "data": "hex"
    }
  ],
  "signature": "signature"
}

5.2. All executions

Fetch a list of relayer task executions with optional filters.

GET /executions

Query Parameters

• configSig: string

• createdAfter: timestamp

• createdBefore: timestamp

• offset: number (default: 0)

• limit: number (default: 20)

Response

[
  {
    "hash": "hex",
    "relayer": "address",
    "configSig": "signature",
    "triggerType": "string",
    "triggerData": {},
    "timestamp": "ISO date",
    "inputs": [
      {
        "signature": "signature",
        "query": {},
        "result": {}
      }
    ],
    "outputs": [
      {
        "op": 0,
        "user": "address",
        "settler": "address",
        "nonce": "hex",
        "deadline": "ISO date",
        "data": "hex",
        "hash": "hex"
      }
    ],
    "signature": "signature",
    "status": "string",
    "createdAt": "ISO date",
    "fee": {
      "fuel": "number",
      "intent": "number",
      "relayerBase": "number",
      "validatorBase": "number",
      "protocolFeePct": "number"
    },
    "validations": [
      { "signature": "signature", "succeeded": true, "description": "string" }
    ],
    "result": {},
    "logs": ["string"]
  }
]

5.3. Find execution

Fetch a specific relayer task execution by its ID. The response may include execution logs.

GET /executions/:hash

Response

{
  "hash": "hex",
  "relayer": "address",
  "configSig": "signature",
  "triggerType": "string",
  "triggerData": {},
  "timestamp": "ISO date",
  "inputs": [
    {
      "signature": "signature",
      "query": {},
      "result": {}
    }
  ],
  "outputs": [
    {
      "op": 0,
      "user": "address",
      "settler": "address",
      "nonce": "hex",
      "deadline": "ISO date",
      "data": "hex",
      "hash": "hex"
    }
  ],
  "signature": "signature",
  "status": "string",
  "createdAt": "ISO date",
  "fee": {
    "fuel": "number",
    "intent": "number",
    "relayerBase": "number",
    "validatorBase": "number",
    "protocolFeePct": "number"
  },
  "validations": [
    { "signature": "signature", "succeeded": true, "description": "string" }
  ],
  "result": {},
  "logs": ["string"]
}

5.4. Add execution validation

Submit a validator signature for an execution.

POST /executions/:hash/validation

Request

{
  "signature": "signature",
  "description": "optional string"
}

---

6. Intents

6.1. All intents

Fetch a list of intents with optional filters.

GET /intents

Query Parameters

• user: address

• settler: address

• deadlineAfter: timestamp

• deadlineBefore: timestamp

• offset: number (default: 0)

• limit: number (default: 20)

Response

[
  {
    "hash": "hex",
    "op": "number: { 0 (swap) | 1 (transfer) | 2 (call) }",
    "user": "address",
    "settler": "address",
    "nonce": "hex",
    "deadline": "ISO date",
    "data": "hex",
    "status": "string: { enqueued | discarded | submitted | succeeded | failed | expired }",
    "events": [
      {
        "level": "string: { info | success | error }",
        "data": "hex",
        "createdAt": "ISO date"
      }
    ],
    "proposals": [
      {
        "solver": "address",
        "data": "hex",
	"deadline": "ISO date",
	"description": "string",
	"signature": "signature",
	"transactionHash": "optional hex",
	"status": "string: { received | discarded | submitted | succeeded | failed }",
      }
    ]
  }
]

6.2. Find intent

Fetch a specific intent by its hash.

GET /intents/:hash

Response

{
  "hash": "hex",
  "op": "number: { 0 (swap) | 1 (transfer) | 2 (call) }",
  "user": "address",
  "settler": "address",
  "nonce": "hex",
  "deadline": "ISO date",
  "data": "hex",
  "status": "string: { enqueued | discarded | submitted | succeeded | failed | expired }",
  "events": [
    {
      "level": "string: { info | success | error }",
      "data": "hex",
      "createdAt": "ISO date"
    }
  ],
  "proposals": [
    {
      "solver": "address",
      "data": "hex",
      "deadline": "ISO date",
      "description": "string",
      "signature": "signature",
      "transactionHash": "optional hex",
      "status": "string: { received | discarded | submitted | succeeded | failed }",
    }
  ]
}

---

7. Miscellaneous

7.1. Settlers

Fetch a list of enabled settlers.

GET /settlers

Response

[
  {
    "chainId": "number",
    "address": "address",
    "createdAt": "ISO date"
  }
]

7.2. Oracles

Fetch an active oracle by address.

GET /oracles/:address

Response

{
  "address": "address",
  "name": "string",
  "active": true
}

7.3. Relayers

Fetch an active relayer by address.

GET /relayers/:address

Response

{
  "address": "address",
  "name": "string",
  "active": true
}

7.4. Execution pricings

Fetch execution pricing history.

GET /execution-pricings

Query Parameters

• createdAfter: timestamp (optional)

• createdBefore: timestamp (optional)

• offset: number (default: 0)

• limit: number (default: 20)

• sort: string (asc | desc, default: desc)

Response

[
  {
    "fuel": "number",
    "intent": "number",
    "relayerBase": "number",
    "validatorBase": "number",
    "rpcCall": "number",
    "priceQuery": "number",
    "relevantTokensQuery": "number",
    "cronTrigger": "number",
    "eventTrigger": "number",
    "protocolFeePct": "number",
    "createdAt": "ISO date"
  }
]

8.2. Health

Check API status.

GET /health

Response

200 'OK'