curl --request POST \
  --url https://api-sb.meld.io/crypto/onramp/requirements-sessions/{id}/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 1,
  "operation": "READ"
}
'

{
  "expiresAt": "2023-11-07T05:31:56Z",
  "next": [
    {
      "code": "<string>",
      "kind": "SUBMIT",
      "serviceProviders": [
        "<string>"
      ],
      "stepId": "<string>",
      "type": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z",
      "fields": [
        {
          "key": "<string>",
          "allowedValues": [
            "<string>"
          ],
          "fieldType": "<string>",
          "jsonSchema": "<string>",
          "label": "<string>"
        }
      ],
      "level": "NONE",
      "reason": "<string>",
      "url": "<string>"
    }
  ],
  "pollAfterMs": 4000,
  "providers": [
    {
      "eligible": true,
      "requirements": [
        {
          "action": {
            "body": {},
            "event": "<string>",
            "expiresAt": "2026-11-04T15:45:00Z",
            "method": "<string>",
            "nextStep": "NONE",
            "path": "<string>",
            "refresh": {
              "body": {},
              "method": "<string>",
              "path": "<string>"
            },
            "type": "CALL",
            "url": "<string>"
          },
          "code": "<string>",
          "currentLevel": "NONE",
          "dependsOn": [
            "<string>"
          ],
          "errorCodes": [
            "<string>"
          ],
          "level": "NONE",
          "missingFields": [
            {
              "allowedValues": [
                "<string>"
              ],
              "fieldType": "<string>",
              "jsonSchema": "<string>",
              "key": "<string>",
              "label": "<string>",
              "providerCode": "<string>",
              "source": "SUMSUB"
            }
          ],
          "process": {
            "automaticSubmissionRetryAllowed": true,
            "code": "<string>",
            "endpoint": "<string>",
            "method": "<string>",
            "pollIntervalMs": 123,
            "pollTimeoutMs": 123,
            "protocol": "<string>",
            "type": "<string>"
          },
          "processStates": [
            {
              "code": "<string>",
              "model": "<string>",
              "reason": "<string>",
              "status": "<string>",
              "submittable": true
            }
          ],
          "processes": [
            "<string>"
          ],
          "reason": "<string>",
          "satisfiedFields": [
            "<string>"
          ],
          "status": "REQUIRED",
          "timing": "PRE_ORDER",
          "type": "VERIFICATION",
          "url": "<string>"
        }
      ],
      "serviceProvider": "<string>",
      "status": "READY"
    }
  ],
  "status": "READY",
  "version": 1,
  "waitingOn": [
    {
      "code": "<string>",
      "serviceProviders": [
        "<string>"
      ],
      "stepId": "<string>",
      "type": "<string>",
      "event": "<string>"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "<string>",
  "errors": [
    "<string>"
  ],
  "message": "<string>",
  "requestId": "<string>",
  "serviceProviderDetails": {
    "code": "5034",
    "message": "Digital currency and blockchain combination is restricted for customer's country"
  },
  "timestamp": "2026-08-14T09:41:22.482+00:00"
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

Headless

Run a requirements session action

Called by the Meld SDK, not by your backend. Meld.ensureReady posts READ to get the session’s plan, and RUN_STEP to run one step of it, with the session token as the bearer. A web page reaches it through your actionProxyUrl proxy, because the Meld API accepts it from a browser only on Meld’s own origins; native apps call it directly. READ changes nothing and takes no X-Idempotency-Key. RUN_STEP takes a new X-Idempotency-Key for each run of a step. Requests are at most 64 KiB, a READ answer at most 256 KiB, and every response carries Cache-Control: no-store. Error bodies are {version, code}, with fieldErrors on a RUN_STEP 400.

POST

crypto

onramp

requirements-sessions

{id}

actions

curl --request POST \
  --url https://api-sb.meld.io/crypto/onramp/requirements-sessions/{id}/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 1,
  "operation": "READ"
}
'

{
  "expiresAt": "2023-11-07T05:31:56Z",
  "next": [
    {
      "code": "<string>",
      "kind": "SUBMIT",
      "serviceProviders": [
        "<string>"
      ],
      "stepId": "<string>",
      "type": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z",
      "fields": [
        {
          "key": "<string>",
          "allowedValues": [
            "<string>"
          ],
          "fieldType": "<string>",
          "jsonSchema": "<string>",
          "label": "<string>"
        }
      ],
      "level": "NONE",
      "reason": "<string>",
      "url": "<string>"
    }
  ],
  "pollAfterMs": 4000,
  "providers": [
    {
      "eligible": true,
      "requirements": [
        {
          "action": {
            "body": {},
            "event": "<string>",
            "expiresAt": "2026-11-04T15:45:00Z",
            "method": "<string>",
            "nextStep": "NONE",
            "path": "<string>",
            "refresh": {
              "body": {},
              "method": "<string>",
              "path": "<string>"
            },
            "type": "CALL",
            "url": "<string>"
          },
          "code": "<string>",
          "currentLevel": "NONE",
          "dependsOn": [
            "<string>"
          ],
          "errorCodes": [
            "<string>"
          ],
          "level": "NONE",
          "missingFields": [
            {
              "allowedValues": [
                "<string>"
              ],
              "fieldType": "<string>",
              "jsonSchema": "<string>",
              "key": "<string>",
              "label": "<string>",
              "providerCode": "<string>",
              "source": "SUMSUB"
            }
          ],
          "process": {
            "automaticSubmissionRetryAllowed": true,
            "code": "<string>",
            "endpoint": "<string>",
            "method": "<string>",
            "pollIntervalMs": 123,
            "pollTimeoutMs": 123,
            "protocol": "<string>",
            "type": "<string>"
          },
          "processStates": [
            {
              "code": "<string>",
              "model": "<string>",
              "reason": "<string>",
              "status": "<string>",
              "submittable": true
            }
          ],
          "processes": [
            "<string>"
          ],
          "reason": "<string>",
          "satisfiedFields": [
            "<string>"
          ],
          "status": "REQUIRED",
          "timing": "PRE_ORDER",
          "type": "VERIFICATION",
          "url": "<string>"
        }
      ],
      "serviceProvider": "<string>",
      "status": "READY"
    }
  ],
  "status": "READY",
  "version": 1,
  "waitingOn": [
    {
      "code": "<string>",
      "serviceProviders": [
        "<string>"
      ],
      "stepId": "<string>",
      "type": "<string>",
      "event": "<string>"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "<string>",
  "errors": [
    "<string>"
  ],
  "message": "<string>",
  "requestId": "<string>",
  "serviceProviderDetails": {
    "code": "5034",
    "message": "Digital currency and blockchain combination is restricted for customer's country"
  },
  "timestamp": "2026-08-14T09:41:22.482+00:00"
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "version": 1,
  "fieldErrors": [
    {
      "key": "email",
      "reason": "REQUIRED"
    }
  ]
}

Authorizations

Authorization

string

header

required

The token of a requirements session. The Meld SDK sends it

Headers

Meld-Version

string

Dated API version to use for this request, e.g. 2026-02-03.

Example:

"2026-02-03"

X-Idempotency-Key

string<uuid>

RUN_STEP only, and required there: a new UUID for each run of a step. Reuse it only to retry the same request after a network failure. READ must not send it

X-Meld-End-User-Ip

string

Set only by your actionProxyUrl proxy: the end user's IP address, which Meld records as the evidence of a terms acceptance once Meld enables it for your account. Otherwise Meld records the address the request came from

Path Parameters

string

required

The session id, 1 to 64 base58 characters

Pattern: ^[1-9A-HJ-NP-Za-km-z]{1,64}$

Body

application/json

READ, or RUN_STEP for one step of next. Any member the operation or the step's kind doesn't take is 400 INVALID_REQUEST

operation

enum<string>

required

Available options:

READ,

RUN_STEP

version

enum<integer>

required

Available options:

1

accepted

boolean

RUN_STEP on an AGREE step: true, once the customer accepted. Meld records the acceptance with its own clock and the customer's IP address

continuation

string

RUN_STEP on a VERIFY_CONTACT step: the continuation of the last outcome, sent with the code in fields.otp

fields

object

RUN_STEP on a COLLECT step: the value for each of the step's field keys, exactly those keys. On a VERIFY_CONTACT step: the email or phone the last outcome asked for, or the otp. At most 20

Show child attributes

refresh

boolean

RUN_STEP on an OPEN_URL step: true. Mints a new page for the step

stepId

string

RUN_STEP: the stepId of a step in next, up to 256 characters. Opaque

Maximum string length: 256

Response

READ: the plan. RUN_STEP: what running the step left to do

RequirementsSnapshot
RequirementsRunOutcome

READ: every session provider's checklist, and the plan across them

expiresAt

string<date-time>

required

When the session token expires

object[]

required

The steps a client can run now, in the order to run them. A step shared by several providers appears once, naming them all

Show child attributes

pollAfterMs

integer<int32>

required

When to read again while waiting: 2000 while a provider process runs, otherwise 4000, 15000 or 30000 as the session ages

Example:

4000

providers

object[]

required

One entry per session provider, in session order

Show child attributes

status

enum<string>

required

With readyWhen ALL: BLOCKED when any provider is, READY when all are, ACTION_REQUIRED when next has steps or a provider has a step to act on, WAITING when only waitingOn is left, UNDETERMINED otherwise. With ANY: READY when one provider is, BLOCKED only when all are. An open set

Available options:

READY,

ACTION_REQUIRED,

WAITING,

BLOCKED,

UNDETERMINED

version

integer<int32>

required

Example:

1

waitingOn

object[]

required

Steps Meld or a provider is running, such as a review

Show child attributes

Crypto

Network Partners

Bank Linking

Payments

Customer

Service Providers

Webhooks

Beta

Run a requirements session action

Authorizations

Headers

Path Parameters

Body

Response