CoinList Passage (Frontline API)

Passage is CoinList's partner API for embedding compliant token sales and tokenized equities. OAuth 2.0 (authorization code + PKCE for users, client credentials for partners), KYC token issuance, document signing, offers, requirements, participations, wallet ownership/allow-listing, and on-chain swap/token reads. 22 operations over a cursor-paginated v1 REST API.

OpenAPI Specification

coinlist-passage-openapi-original.json Raw ↑
{
  "components": {
    "responses": {},
    "schemas": {
      "RequirementStatuses": {
        "properties": {
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "requirement_statuses"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_id": {
            "description": "The offer ID",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "statuses": {
            "additionalProperties": {
              "anyOf": [
                {
                  "enum": [
                    "not_started",
                    "in_progress",
                    "action_needed",
                    "completed",
                    "rejected"
                  ],
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                {
                  "description": "Object form, used when the status carries extra data: the action-needed reason and/or the Sumsub flow that resolves the requirement (kyc_level + kyc_reset, to be sent to the kyc-token endpoint as-is).",
                  "properties": {
                    "action": {
                      "enum": [
                        "kyc_not_verified",
                        "update_pii_data"
                      ],
                      "type": "string",
                      "x-struct": null,
                      "x-validate": null
                    },
                    "kyc_level": {
                      "description": "The Sumsub verification level that resolves this requirement",
                      "enum": [
                        "Sorting_KYC_Level",
                        "BasicKYCLevel",
                        "AccreditationIndividual_FullVerification"
                      ],
                      "type": "string",
                      "x-struct": null,
                      "x-validate": null
                    },
                    "kyc_reset": {
                      "description": "Whether the Sumsub applicant must be reset before starting the flow (redoing an already-approved level, e.g. to update stale PII)",
                      "type": "boolean",
                      "x-struct": null,
                      "x-validate": null
                    },
                    "status": {
                      "enum": [
                        "not_started",
                        "in_progress",
                        "action_needed",
                        "completed",
                        "rejected"
                      ],
                      "type": "string",
                      "x-struct": null,
                      "x-validate": null
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "type": "object",
                  "x-struct": null,
                  "x-validate": null
                }
              ],
              "x-struct": null,
              "x-validate": null
            },
            "description": "Map of requirement ID to status",
            "type": "object",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "offer_id",
          "statuses"
        ],
        "title": "RequirementStatuses",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.RequirementStatuses",
        "x-validate": null
      },
      "Participation": {
        "additionalProperties": false,
        "description": "An offer participation",
        "properties": {
          "amount": {
            "description": "The participation amount",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "amount_string": {
            "description": "The participation amount formatted as a human-readable string",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "asset": {
            "description": "The asset details for the participation",
            "properties": {
              "code": {
                "description": "The asset code (symbol)",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "fractional_digits": {
                "description": "The number of fractional digits for the asset",
                "type": "integer",
                "x-struct": null,
                "x-validate": null
              },
              "id": {
                "description": "The asset ID",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "name": {
                "description": "The asset name",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "required": [
              "id",
              "code",
              "name",
              "fractional_digits"
            ],
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "chain": {
            "description": "The chain for the participation contract",
            "enum": [
              "ethereum_sepolia",
              "base_sepolia",
              "solana_devnet",
              "ethereum_mainnet",
              "base_mainnet",
              "solana_mainnet"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "id": {
            "description": "Unique identifier for the object.",
            "example": "05edea81-98a7-4582-aa7c-040d57cb1858",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "inserted_at": {
            "description": "When the participation was created",
            "example": "2025-01-01T00:00:00.000000Z",
            "format": "date-time",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "participation"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_id": {
            "description": "The ID of the offer",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_option_id": {
            "description": "The ID of the offer option",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "status": {
            "description": "The participation status",
            "enum": [
              "prepared",
              "pending",
              "submitted",
              "completed",
              "failed",
              "remit_submitted",
              "remitted",
              "remit_failed"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "updated_at": {
            "description": "When the participation was last updated",
            "example": "2025-01-01T00:00:00.000000Z",
            "format": "date-time",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "wallet_address": {
            "description": "The wallet address for the participation",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "id",
          "offer_id",
          "offer_option_id",
          "status",
          "amount",
          "amount_string",
          "asset",
          "chain"
        ],
        "title": "Participation",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.Participation",
        "x-validate": null
      },
      "OauthIntrospect": {
        "description": "Token introspection response. When active is false, only that field is returned.",
        "properties": {
          "active": {
            "description": "Whether the token is active.",
            "example": true,
            "type": "boolean",
            "x-struct": null,
            "x-validate": null
          },
          "client_id": {
            "description": "The client identifier for the OAuth 2.0 client that requested this token.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "exp": {
            "description": "The Unix timestamp when the token expires.",
            "example": 1704067200,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "iat": {
            "description": "The Unix timestamp when the token was issued.",
            "example": 1704063600,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "iss": {
            "description": "The issuer of the token.",
            "example": "https://api.example.com",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "scope": {
            "description": "A space-separated list of scopes associated with the token.",
            "example": "read write",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "sub": {
            "description": "The subject of the token (user ID).",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "username": {
            "description": "The username of the resource owner.",
            "example": "user@example.com",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "active"
        ],
        "title": "OauthIntrospect",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Oauth.Schemas.OauthIntrospect",
        "x-validate": null
      },
      "OfferRequirements": {
        "properties": {
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "offer_requirements"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_id": {
            "description": "The offer ID",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "options": {
            "additionalProperties": {
              "properties": {
                "data": {
                  "items": {
                    "$ref": "#/components/schemas/OptionRequirement"
                  },
                  "type": "array",
                  "x-struct": null,
                  "x-validate": null
                },
                "object": {
                  "description": "String representing the object's type. Objects of the same type share the same value.",
                  "enum": [
                    "list"
                  ],
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                }
              },
              "required": [
                "object",
                "data"
              ],
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "description": "Map of option ID to list of requirements for that option",
            "type": "object",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "offer_id",
          "options"
        ],
        "title": "OfferRequirements",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.OfferRequirements",
        "x-validate": null
      },
      "SwapOutputToken": {
        "additionalProperties": false,
        "description": "ERC-20 metadata of a swap contract's output token.",
        "properties": {
          "decimals": {
            "description": "ERC-20 token decimals",
            "example": 6,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "name": {
            "description": "ERC-20 token name",
            "example": "USD Coin",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "swap_output_token"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "symbol": {
            "description": "ERC-20 token symbol",
            "example": "USDC",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "name",
          "symbol",
          "decimals"
        ],
        "title": "SwapOutputToken",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.SwapOutputToken",
        "x-validate": null
      },
      "TokenBalance": {
        "additionalProperties": false,
        "description": "Current on-chain ERC-20 balance of an owner address.",
        "properties": {
          "balance": {
            "description": "The balance as a uint256 decimal string in the token's smallest unit",
            "example": "1000000",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "token_balance"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "balance"
        ],
        "title": "TokenBalance",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.TokenBalance",
        "x-validate": null
      },
      "CreateParticipation": {
        "description": "Parameters for creating an offer participation",
        "properties": {
          "amount": {
            "description": "The participation amount",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "approval_transaction_hash": {
            "description": "The approval transaction hash",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "asset_id": {
            "description": "The ID of the asset",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "chain": {
            "description": "The blockchain chain for the funding contract",
            "enum": [
              "ethereum_sepolia",
              "base_sepolia",
              "solana_devnet",
              "ethereum_mainnet",
              "base_mainnet",
              "solana_mainnet"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_id": {
            "description": "The ID of the offer",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "offer_option_id": {
            "description": "The ID of the offer option",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "wallet_address": {
            "description": "The wallet address",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "offer_id",
          "offer_option_id",
          "chain",
          "wallet_address",
          "amount",
          "asset_id",
          "approval_transaction_hash"
        ],
        "title": "CreateParticipation",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.CreateParticipation",
        "x-validate": null
      },
      "VerifyOwnershipRequest": {
        "description": "Parameters consumed by VerifyOwnershipPlug to verify wallet ownership.",
        "properties": {
          "chain": {
            "description": "The blockchain network the wallet belongs to.",
            "enum": [
              "ethereum_sepolia",
              "base_sepolia",
              "solana_devnet",
              "ethereum_mainnet",
              "base_mainnet",
              "solana_mainnet"
            ],
            "example": "ethereum_sepolia",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "signature": {
            "description": "The cryptographic signature of the challenge message.",
            "example": "0xdeadbeef",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "wallet_address": {
            "description": "The wallet address to verify. For EVM chains, must be a valid Ethereum address (normalized to lowercase).",
            "example": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "wallet_address",
          "chain",
          "signature"
        ],
        "title": "VerifyOwnershipRequest",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.VerifyOwnershipRequest",
        "x-validate": null
      },
      "Error": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "description": "A human-readable message providing more details about the error.",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "errors": {
            "additionalProperties": {
              "items": {
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "type": "array",
              "x-struct": null,
              "x-validate": null
            },
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "event_id": {
            "description": "The unique identifier for the error event. This is useful for tracking and debugging.",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "message": {
            "description": "For some errors that could be handled programmatically, a short string indicating the error code reported.",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "type": {
            "description": "The type of error returned. One of `api_error`, `invalid_request_error`",
            "enum": [
              "api_error",
              "invalid_request_error"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "type",
          "message"
        ],
        "title": "Error",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.ApiError",
        "x-validate": null
      },
      "Offer": {
        "additionalProperties": false,
        "description": "Offer summary",
        "properties": {
          "banner_url": {
            "description": "The URL for the offer banner",
            "format": "uri",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "ends_at": {
            "description": "When the offer ends",
            "example": "2025-01-01T00:00:00.000000Z",
            "format": "date-time",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "id": {
            "description": "Unique identifier for the object.",
            "example": "05edea81-98a7-4582-aa7c-040d57cb1858",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "logo_url": {
            "description": "The URL for the offer logo",
            "format": "uri",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "offer"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "options": {
            "description": "List of offer options",
            "items": {
              "$ref": "#/components/schemas/OfferOption"
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "slug": {
            "description": "The slug identifier of the offer",
            "example": "example-offer",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "starts_at": {
            "description": "When the offer starts",
            "example": "2025-01-01T00:00:00.000000Z",
            "format": "date-time",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "tagline": {
            "description": "Tagline text for the offer (English)",
            "example": "Example Offer Tagline",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "type": {
            "description": "The type of the offer",
            "enum": [
              "sale",
              "swap"
            ],
            "example": "sale",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "id",
          "slug",
          "type",
          "options"
        ],
        "title": "Offer",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.Offer",
        "x-validate": null
      },
      "SwapStatus": {
        "additionalProperties": false,
        "description": "Current status flags of a Superstate swap contract.",
        "properties": {
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "swap_status"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "stopped": {
            "description": "The contract's stopped() bitmask as a uint256 decimal string. Zero means no functionality is stopped.",
            "example": "0",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "swap_level": {
            "description": "The contract's SWAP_LEVEL() flag as a uint256 decimal string",
            "example": "4",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "stopped",
          "swap_level"
        ],
        "title": "SwapStatus",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.SwapStatus",
        "x-validate": null
      },
      "Pii": {
        "description": "The user's PII used to pre-fill tax forms. Fields that are unavailable are null.",
        "properties": {
          "date_of_birth": {
            "description": "Date of birth as an ISO 8601 date (YYYY-MM-DD). Null for companies and when unavailable.",
            "example": "1990-01-15",
            "format": "date",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "full_legal_name": {
            "description": "Full legal name. For persons: first, middle and last name joined. For companies: the company name.",
            "example": "Aleksander Nowak",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "jurisdiction": {
            "description": "Jurisdiction of the entity, sourced from the entity's address country",
            "nullable": true,
            "properties": {
              "iso_2": {
                "description": "ISO 3166-1 alpha-2 country code",
                "example": "PL",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "name": {
                "description": "Country display name",
                "example": "Poland",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "required": [
              "iso_2",
              "name"
            ],
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "kind": {
            "description": "Kind of the entity the PII belongs to",
            "enum": [
              "person",
              "company"
            ],
            "example": "person",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "object": {
            "description": "String representing the object's type. Objects of the same type share the same value.",
            "enum": [
              "user_pii"
            ],
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "permanent_address": {
            "description": "Permanent address of the entity",
            "properties": {
              "city": {
                "example": "Warsaw",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "country": {
                "description": "ISO 3166-1 alpha-2 country code",
                "example": "PL",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "postal_code": {
                "example": "00-001",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "state": {
                "description": "State or region code",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "street": {
                "example": "ul. Nowy Świat 12",
                "nullable": true,
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "required": [
              "street",
              "city",
              "state",
              "postal_code",
              "country"
            ],
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "tax_id": {
            "description": "Tax identification number. For persons: SSN or foreign TIN. For companies: EIN.",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "object",
          "kind",
          "full_legal_name",
          "date_of_birth",
          "jurisdiction",
          "tax_id",
          "permanent_address"
        ],
        "title": "Pii",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.Pii",
        "x-validate": null
      },
      "CreateKycTokenRequest": {
        "additionalProperties": false,
        "properties": {
          "level_name": {
            "default": "Sorting_KYC_Level",
            "description": "The Sumsub verification level to start. Determines which screens the Sumsub WebSDK shows.",
            "enum": [
              "Sorting_KYC_Level",
              "BasicKYCLevel",
              "AccreditationIndividual_FullVerification"
            ],
            "example": "Sorting_KYC_Level",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "reset": {
            "default": false,
            "description": "Reset the Sumsub applicant before issuing the token, so an already-approved level can be executed again (e.g. to update stale PII). Send the kyc_reset value from the requirement status. Must not be sent when refreshing an expired token mid-flow, or the user's in-progress submission is wiped.",
            "type": "boolean",
            "x-struct": null,
            "x-validate": null
          }
        },
        "title": "CreateKycTokenRequest",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.CreateKycTokenRequest",
        "x-validate": null
      },
      "OptionRequirementJurisdictionFilter": {
        "properties": {
          "country_iso_2": {
            "description": "The ISO 3166-1 alpha-2 country code",
            "example": "US",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "regions": {
            "description": "List of region codes for the country",
            "example": [
              "CA",
              "NY"
            ],
            "items": {
              "type": "string",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "country_iso_2"
        ],
        "title": "OptionRequirementJurisdictionFilter",
        "type": "object",
        "x-struct": "Elixir.FrontlineAPIWeb.OpenApi.Schemas.OptionRequirement.JurisdictionFilter",
        "x-validate": null
      },
      "OfferOption": {
        "additionalProperties": false,
        "description": "An option within an offer",
        "properties": {
          "bid_increment": {
            "description": "Decimal string",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "floor_price_usd": {
            "description": "Decimal string",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "id": {
            "description": "Unique identifier for the object.",
            "example": "05edea81-98a7-4582-aa7c-040d57cb1858",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "minimum_purchase_usd": {
            "description": "Decimal string",
            "nullable": true,
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "price_usd": {
            "description": "Decimal strin

# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coinlist/refs/heads/main/openapi/coinlist-passage-openapi-original.json